{
  "openapi": "3.1.0",
  "info": {
    "title": "HomePulse API",
    "description": "Global home intelligence API. AI-synthesized home maintenance checklists, improvement ROI analysis, neighborhood research, smart home integration, energy efficiency guidance, contractor task briefings, home value estimation, rental market analysis, and renovation planning. Serves homeowners, renters, real estate investors, and property managers in any country. Angi, Thumbtack, home warranty, and home insurance affiliate links auto-appended to relevant endpoints. All endpoints support any language via ?lang=. Pricing: $0.08\u2013$0.15 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://homepulse-seven.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://homepulse-seven.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Omit to receive a 402 with payment requirements."
      }
    }
  },
  "paths": {
    "/api/home/value": {
      "get": {
        "summary": "Home value estimate",
        "description": "Estimated market value range (low/mid/high) with confidence rating, comparable sales, market trend, and best time to act.",
        "operationId": "homeValue",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Street address"
          },
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ZIP code"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Home value estimate with market context and comparable sales"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run before listing or refinancing; pairs with PropPulse /api/prop/refi for refinance decision; pairs with /api/home/improve for pre-sale improvements with highest ROI"
      }
    },
    "/api/home/neighborhood": {
      "get": {
        "summary": "Neighborhood analysis",
        "description": "School ratings, relative safety, walkability score, neighborhood character, demographics, and best-for/not-ideal-for breakdown.",
        "operationId": "homeNeighborhood",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Neighborhood profile with schools, safety, walkability, and character"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run before buying or renting; pairs with PropPulse /api/prop/refi and /api/prop/mortgage for purchase decision; pairs with /api/home/value"
      }
    },
    "/api/home/improve": {
      "get": {
        "summary": "Home improvement ROI analysis",
        "description": "ROI summary (cost, value added, recoup rating), best-for analysis (selling/staying/both), DIY vs contractor breakdown, materials list with Amazon links, and top national ROI projects.",
        "operationId": "homeImprove",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "project",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Project type (e.g. kitchen-remodel, deck-addition, new-roof)"
          },
          {
            "name": "home_value",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Current estimated home value in USD"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Improvement ROI analysis with materials list and DIY guidance"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "ROI-ranked improvements \u2014 chain to /api/home/roi for specific project; pairs with PropPulse /api/prop/valuate for home value impact; Angi/Thumbtack contractor links auto-appended"
      }
    },
    "/api/home/maintain": {
      "get": {
        "summary": "Seasonal maintenance checklist",
        "description": "Prioritized task list (urgent/high/medium/low) with cost estimates, DIY feasibility, time estimates, tools/supplies with Amazon links, and total season cost range.",
        "operationId": "homeMaintain",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "season",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "spring",
                "summer",
                "fall",
                "winter"
              ]
            },
            "description": "Defaults to current season"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "US region or state (e.g. Northeast, Pacific Northwest)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Seasonal maintenance checklist with costs and supplies"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run seasonally \u2014 Amazon + Angi contractor affiliate links auto-appended; pairs with /api/home/improve for items that reveal larger upgrade opportunities; pairs with /api/home/energy for efficiency maintenance items"
      }
    },
    "/api/home/rent": {
      "get": {
        "summary": "Rental market analysis",
        "description": "Rent ranges by bedroom count, market trend, HUD fair market rent (official government data), best neighborhoods to rent, and renting vs buying comparison.",
        "operationId": "homeRent",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter state code required for HUD FMR data"
          },
          {
            "name": "bedrooms",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "county",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "County name hint for HUD FMR matching"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rental market analysis with price ranges and HUD data"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Rental market analysis \u2014 pairs with PropPulse /api/prop/landlord for landlord operations; pairs with /api/home/neighborhood for location context"
      }
    }
  }
}