{
  "openapi": "3.1.0",
  "info": {
    "title": "LandlordIQ — RentalAnalytics Rental Market API",
    "version": "0.1.0",
    "summary": "HUD-anchored rental market intelligence for U.S. ZIP codes and metros.",
    "description": "LandlordIQ is an MCP-compatible HTTP API exposing seven read-only tools for rental market intelligence: market rent, vacancy, rent growth, cap-rate benchmarks, lease-renewal recommendations, a one-call landlord summary, and city landlord-tenant regulations.\n\nEvery successful response uses a consistent envelope: `data` (the result, or null on error), `confidence_score` (integer 0-100), `data_freshness` (ISO 8601 timestamp of the response), `data_source` (human-readable provenance string), and `error` (null when OK, otherwise a human-readable message).\n\nData semantics: rent figures are anchored to public HUD FY2024 Fair Market Rents and aged forward with BLS CPI Shelter. Vacancy, rent growth, and cap-rate fields are estimated blends of public datasets (ApartmentList, Census ACS, CBRE/NCREIF tiers) and are labeled as estimated. Regulation summaries are plain-English editorial digests, NOT legal advice. Always read `data_source` and `confidence_score` before acting on a value.",
    "contact": { "name": "RentalAnalytics API", "email": "api@rentalanalytics.com", "url": "https://rentalanalytics.com/mcp/" },
    "license": { "name": "Free tier; data sources retain original licenses", "url": "https://rentalanalytics.com/legal/terms.html" }
  },
  "servers": [
    { "url": "https://api.rentalanalytics.com", "description": "Production LandlordIQ server" },
    { "url": "http://localhost:8787", "description": "Local development server" }
  ],
  "security": [ {}, { "ApiKeyAuth": [] } ],
  "tags": [
    { "name": "rent", "description": "Rent estimates and growth" },
    { "name": "deal", "description": "Underwriting benchmarks" },
    { "name": "market", "description": "Market-level summaries" },
    { "name": "compliance", "description": "Landlord-tenant regulations" },
    { "name": "meta", "description": "Discovery and health" }
  ],
  "paths": {
    "/get_market_rent": {
      "get": {
        "operationId": "get_market_rent",
        "tags": ["rent"],
        "summary": "HUD-anchored market rent estimate by ZIP, bedrooms, and property type.",
        "description": "Returns a low/median/high market rent range for a U.S. ZIP code. Typical confidence 72-92 for ZIPs in the sample dataset; ~35 for out-of-sample ZIPs (flagged via data.fallback=true and a 'national fallback' data_source).",
        "parameters": [
          { "name": "zip_code", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "example": "78704", "description": "5-digit U.S. ZIP code." },
          { "name": "bedrooms", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 8, "default": 2 }, "description": "Bedroom count. 5+ extrapolated at +18%/bedroom." },
          { "name": "property_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["apartment", "single_family", "townhouse", "condo", "duplex_unit"], "default": "apartment" } }
        ],
        "responses": { "200": { "description": "Rent estimate envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "zip": "78704", "bedrooms": 2, "property_type": "apartment", "median_rent": 2276, "low": 1958, "high": 2641, "percentile_in_metro": 52, "comparable_count": 60, "city": "Austin", "state": "TX", "metro": "Austin-Round Rock-Georgetown, TX MSA", "fallback": false }, "confidence_score": 90, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "HUD FMR FY2024 (public) + BLS CPI Shelter trend", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/get_vacancy_rate": {
      "get": {
        "operationId": "get_vacancy_rate",
        "tags": ["market"],
        "summary": "Metro-level rental vacancy rate for a covered U.S. city (estimated).",
        "parameters": [
          { "name": "city", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Austin" },
          { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "TX" },
          { "name": "property_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["single_family", "multifamily_5_plus"] }, "description": "Optional adjustment; omit for all-types." }
        ],
        "responses": { "200": { "description": "Vacancy envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "city": "Austin", "state": "TX", "metro_tier": "Tier 1", "vacancy_pct": 8.1, "as_of": "2024-Q4", "property_type": "all" }, "confidence_score": 70, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "U.S. Census ACS + ApartmentList Vacancy Index (estimated blend)", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/get_rent_growth": {
      "get": {
        "operationId": "get_rent_growth",
        "tags": ["rent"],
        "summary": "Year-over-year rent growth and 12-month forward projection for a metro (estimated).",
        "parameters": [
          { "name": "metro", "in": "query", "required": true, "schema": { "type": "string" }, "example": "austin-tx", "description": "Metro slug (e.g. 'austin-tx') or city name." },
          { "name": "timeframe", "in": "query", "required": false, "schema": { "type": "string", "enum": ["yoy", "1yr", "12mo_projection", "forecast", "cagr", "5yr"], "default": "yoy" } }
        ],
        "responses": { "200": { "description": "Rent growth envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "metro": "austin-tx", "city": "Austin", "state": "TX", "timeframe": "yoy", "growth_pct": -3.4, "yoy_pct": -3.4, "projected_12mo_pct": -0.2, "cagr_5yr_pct": 1.5, "as_of": "2024-Q4" }, "confidence_score": 60, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "BLS CPI Shelter + ApartmentList National Rent Report (estimated blend)", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/get_cap_rate_benchmark": {
      "get": {
        "operationId": "get_cap_rate_benchmark",
        "tags": ["deal"],
        "summary": "Typical cap-rate band for a metro tier and property type (estimated).",
        "parameters": [
          { "name": "zip_code", "in": "query", "required": false, "schema": { "type": "string" }, "example": "78704", "description": "Used to infer metro tier; defaults to Tier 2 if unknown." },
          { "name": "property_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["single_family", "small_multifamily_2_4", "multifamily_5_plus", "condo"], "default": "single_family" } }
        ],
        "responses": { "200": { "description": "Cap-rate band envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "zip": "78704", "property_type": "single_family", "metro_tier": "Tier 1", "cap_rate_low": 4.5, "cap_rate_mid": 5.5, "cap_rate_high": 6.5, "tier_label": "Primary / gateway metro", "as_of": "2024-Q4" }, "confidence_score": 72, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "CBRE U.S. Cap Rate Survey + NCREIF metro tiers (estimated)", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/get_lease_renewal_recommendation": {
      "get": {
        "operationId": "get_lease_renewal_recommendation",
        "tags": ["rent"],
        "summary": "Compare current rent to market and recommend a renewal rent + retention-risk tier.",
        "parameters": [
          { "name": "current_rent", "in": "query", "required": true, "schema": { "type": "number", "minimum": 1 }, "example": 1800 },
          { "name": "zip_code", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "example": "78704" },
          { "name": "bedrooms", "in": "query", "required": false, "schema": { "type": "integer", "default": 2 } }
        ],
        "responses": { "200": { "description": "Lease renewal envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "current_rent": 1800, "market_rent": 2276, "gap_pct": 26.4, "recommended_rent": 1980, "recommendation": "Reposition: 8-12% increase — high retention risk; budget for vacancy if tenant leaves", "retention_risk": "high", "zip": "78704", "bedrooms": 2 }, "confidence_score": 85, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "HUD FMR + BLS CPI Shelter + NMHC turnover-cost survey", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/get_landlord_market_summary": {
      "get": {
        "operationId": "get_landlord_market_summary",
        "tags": ["market"],
        "summary": "One-call rollup for a ZIP: rent by bedroom, vacancy, YoY growth, cap-rate band, regulation snapshot.",
        "description": "The most efficient single call for an agent that needs full context on a ZIP. Combines outputs of several tools into one envelope.",
        "parameters": [
          { "name": "zip_code", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "example": "78704" }
        ],
        "responses": { "200": { "description": "Market summary envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "zip": "78704", "city": "Austin", "state": "TX", "metro_tier": "Tier 1", "median_rent_by_bedroom": { "0br": 1740, "1br": 1868, "2br": 2276, "3br": 2996, "4br": 3511 }, "vacancy_pct": 8.1, "yoy_rent_growth_pct": -3.4, "cap_rate_band_sfr": { "low": 4.5, "mid": 5.5, "high": 6.5 }, "regulation_summary": { "rent_control": "No (Texas state preemption)", "late_fee_cap_pct": 12, "notice_to_vacate_days": 30 }, "as_of": "2024-Q4" }, "confidence_score": 68, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "HUD FMR + Census ACS + BLS + curated regulation dataset", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/get_regulations": {
      "get": {
        "operationId": "get_regulations",
        "tags": ["compliance"],
        "summary": "Plain-English landlord-tenant regulation summary for a covered U.S. city.",
        "description": "Editorial digest covering the top 20 U.S. cities. NOT legal advice — confirm with local counsel.",
        "parameters": [
          { "name": "city", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Austin" },
          { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "TX" }
        ],
        "responses": { "200": { "description": "Regulation envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "city": "Austin", "state": "TX", "rent_control": "No (Texas state preemption)", "late_fee_cap_pct": 12, "security_deposit_max": "No statutory cap", "notice_to_vacate_days": 30, "just_cause_eviction": false, "reviewed_on": "2024-10-15", "slug": "austin-tx", "_disclaimer": "Plain-English summary, NOT legal advice. Confirm with local counsel." }, "confidence_score": 80, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "RentalAnalytics curated landlord-tenant regulation dataset (top-20 U.S. cities)", "error": null } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/manifest.json": {
      "get": { "operationId": "get_manifest", "tags": ["meta"], "summary": "MCP-compatible tool-discovery manifest.", "responses": { "200": { "description": "Manifest with tool catalog and auth model." } } }
    },
    "/healthz": {
      "get": { "operationId": "healthz", "tags": ["meta"], "summary": "Liveness probe.", "responses": { "200": { "description": "Service is up." } } }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Optional. Omit for the free tier (60 req/hr/IP). Supply a provisioned key for the paid tier (10,000 req/day)." }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "required": ["data", "confidence_score", "data_freshness", "data_source", "error"],
        "properties": {
          "data": { "type": ["object", "null"], "description": "Result object, or null when error is set." },
          "confidence_score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "0 on error. 72-92 high (direct HUD anchor); 50-71 moderate (blended/estimated); 1-49 low (fallback/extrapolated)." },
          "data_freshness": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when this response was generated." },
          "data_source": { "type": "string", "description": "Human-readable provenance. Contains 'estimated' when the value is a blended estimate rather than a direct public figure." },
          "error": { "type": ["string", "null"], "description": "Null on success; human-readable message on failure." }
        }
      }
    },
    "responses": {
      "Error": { "description": "Bad request — same envelope with data=null, confidence_score=0, and a human-readable error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": null, "confidence_score": 0, "data_freshness": "2024-10-15T14:23:11.000Z", "data_source": "HUD FMR FY2024 (public)", "error": "zip_code must be a 5-digit U.S. ZIP" } } } },
      "RateLimited": { "description": "Rate limit exceeded. Inspect X-RateLimit-Reset for the reset epoch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }
    }
  }
}