{"openapi":"3.1.0","info":{"title":"DwellData — Multifamily Real Estate Deals Feed","version":"1.0.0","description":"DwellData: deal-level US multifamily records for AI agents. Paid endpoints use x402 (USDC on Base).","contact":{"email":"seanepage@gmail.com"}},"servers":[{"url":"https://dwelldata.io"}],"paths":{"/api/meta":{"get":{"summary":"Free discovery metadata","security":[],"responses":{"200":{"description":"Coverage, freshness, pricing, schema notes"}}}},"/api/deals/ids":{"get":{"summary":"Free deal-id index (top 50 active deals)","security":[],"responses":{"200":{"description":"id, address, price, units, cap, score for the top 50 active deals — use any id in /api/deals/{id}/report"}}}},"/api/lookup":{"get":{"summary":"Address or parcel lookup — one property, one call (x402, $0.02/call)","description":"Everything Hermes knows about one property, keyed by street address or parcel id (APN): matching multifamily listings (with underwriting), county tax-delinquency signals, and sheriff-sale auction records, each row carrying its public source URL. Pass address, apn, or both (apn matches distress + auction records only — listings carry no parcel id). A query that matches nothing returns a free 404 with the coverage explanation.","parameters":[{"name":"address","in":"query","schema":{"type":"string"},"description":"Street address, e.g. \"2615 N Gettysburg Ave\". Required unless apn is given."},{"name":"apn","in":"query","schema":{"type":"string"},"description":"Parcel id / APN, e.g. \"H33300821 0125\" (aliases: parcel). Spaces and dashes are ignored. Required unless address is given."},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"},"description":"Two-letter state"}],"responses":{"200":{"description":"Matching listings + distress signals + auctions with match_basis and coverage notes"},"402":{"description":"Payment required (x402 v2, USDC on Base)"},"404":{"description":"No match in any feed (not billed)"}}}},"/api/deals/basic":{"get":{"summary":"Basic tier: card-level listings (x402, $0.01/call)","description":"Entry tier: every active listing with card-level fields (address, price, units, advertised cap rate, listing URL, freshness) and the same optional query filters as the full feed — without computed NOI/DSCR, HUD underwriting, or scoring.","responses":{"200":{"description":"Card-level records, cap-rate-ranked"},"402":{"description":"Payment required (x402 v2, USDC on Base)"}}}},"/api/deals":{"get":{"summary":"Full active deals feed (x402, $0.05/call)","description":"Optional query filters (AND-combined) return only the matching slice at the same per-call price.","parameters":[{"name":"state","in":"query","schema":{"type":"string"},"description":"Two-letter state, e.g. OH"},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"min_price","in":"query","schema":{"type":"number"}},{"name":"max_price","in":"query","schema":{"type":"number"}},{"name":"min_cap","in":"query","schema":{"type":"number"},"description":"Minimum advertised cap rate %"},{"name":"min_units","in":"query","schema":{"type":"integer"}},{"name":"max_units","in":"query","schema":{"type":"integer"}},{"name":"min_score","in":"query","schema":{"type":"integer"},"description":"Minimum composite deal_score (0-100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["Hot","Warm","Pass"]}}],"responses":{"200":{"description":"Active records (deal_score-ranked) with typed underwriting + intelligence fields"},"402":{"description":"Payment required (x402 v2, USDC on Base)"}}}},"/api/deals/hot":{"get":{"summary":"Hot deals only (x402, $0.02/call)","responses":{"200":{"description":"Deals with 8.5%+ advertised cap and computed DSCR"},"402":{"description":"Payment required (x402 v2, USDC on Base)"}}}},"/api/signals":{"get":{"summary":"County tax-delinquency distress signals (x402, $0.03/call)","description":"Off-market lead sourcing: county tax-delinquent property records with owner name, parcel id, delinquent amount, and the public-record source URL for every row. Rows with a street address are mail-ready (has_address=true); the rest carry address_status=pending_parcel_lookup while enrichment drains.","parameters":[{"name":"county","in":"query","schema":{"type":"string"},"description":"Substring match, e.g. Hamilton or Montgomery"},{"name":"signal_type","in":"query","schema":{"type":"string"},"description":"e.g. tax_delinquent"},{"name":"min_amount","in":"query","schema":{"type":"number"},"description":"Minimum delinquent amount in USD"},{"name":"has_address","in":"query","schema":{"type":"boolean"},"description":"true = only rows with a street address"}],"responses":{"200":{"description":"Signal records, amount-ranked, with typed address_status and schema notes"},"402":{"description":"Payment required (x402 v2, USDC on Base)"}}}},"/api/auctions":{"get":{"summary":"Foreclosure auction calendar (x402, $0.03/call)","description":"Upcoming sheriff-sale foreclosure auctions from official county court-journal publications: sale date, property address, appraised value, opening-bid floor (published minimum for tax sales; statutory two-thirds of appraisal for mortgage sales), case number, plaintiff/defendant, and the public source URL for every row. Defaults to future sales only.","parameters":[{"name":"county","in":"query","schema":{"type":"string"},"description":"Substring match, e.g. Summit or Mahoning"},{"name":"from_date","in":"query","schema":{"type":"string","format":"date"},"description":"Earliest sale date (default: today)"},{"name":"to_date","in":"query","schema":{"type":"string","format":"date"},"description":"Latest sale date"},{"name":"min_appraised","in":"query","schema":{"type":"number"},"description":"Minimum appraised value in USD"},{"name":"include_past","in":"query","schema":{"type":"boolean"},"description":"true = include past sale dates (history)"}],"responses":{"200":{"description":"Auction records, sale-date-ranked, with typed opening_bid basis and schema notes"},"402":{"description":"Payment required (x402 v2, USDC on Base)"}}}},"/api/leads":{"get":{"summary":"Scored off-market seller leads, premium (x402, $0.25/call)","description":"Mail-ready direct-to-seller leads built exclusively from public records: every lead carries a street address, a distress signal verified within the last 7 days (county tax delinquency or upcoming sheriff-sale foreclosure), a deterministic 0-100 lead_score, and a machine-readable score rationale. Sorted by lead_score. No skip-traced personal contact data is included.","parameters":[{"name":"county","in":"query","schema":{"type":"string"},"description":"Substring match, e.g. Montgomery or Summit"},{"name":"min_score","in":"query","schema":{"type":"integer"},"description":"Minimum lead_score (0-100)"},{"name":"lead_type","in":"query","schema":{"type":"string","enum":["tax_delinquent","sheriff_sale_auction"]}}],"responses":{"200":{"description":"Scored lead records with rationale, freshness, and public source URL"},"402":{"description":"Payment required (x402 v2, USDC on Base)"}}}},"/api/leads/exclusive":{"get":{"summary":"One exclusive lead — one buyer, ever (x402, $1.00/call)","description":"Buys the single top-scored available lead outright: on purchase it is permanently removed from the shared /api/leads pool and never sold to anyone else. Optional filters narrow which lead you get. A 404 (no lead matches) is not billed.","parameters":[{"name":"county","in":"query","schema":{"type":"string"}},{"name":"min_score","in":"query","schema":{"type":"integer"}},{"name":"lead_type","in":"query","schema":{"type":"string","enum":["tax_delinquent","sheriff_sale_auction"]}}],"responses":{"200":{"description":"The claimed exclusive lead"},"402":{"description":"Payment required (x402 v2, USDC on Base)"},"404":{"description":"No available lead matches (not billed)"}}}},"/api/deals/{id}/report":{"get":{"summary":"Premium per-property report (x402, $1.50/call)","description":"One decision-ready report for a single deal: underwriting (claimed vs HUD), DSCR, matched county distress signals with source URLs, three-path scoring, and a target-cap suggested offer range. A bad id (400) or unknown deal (404) is not billed. GET /api/meta returns a worked example URL with a live deal id (example_report).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Deal UUID — the 'id' field of any record from GET /api/deals. Do not send the literal '{id}'."}],"responses":{"200":{"description":"Full report"},"400":{"description":"Invalid id (not billed)"},"402":{"description":"Payment required (x402 v2, USDC on Base)"},"404":{"description":"Unknown deal (not billed)"}}}}}}