{"openapi":"3.1.0","info":{"title":"HouseMe.ai — Paige for AI agents","version":"1.0.0","description":"Zero-auth real-estate answers from live MLS data. Coverage: Ontario, Canada (Toronto/GTA) and the Mid-Atlantic US (DC, Maryland, Virginia and neighbors). Ask in natural language; get Markdown or JSON with listings, a conversation_id for follow-ups, and a continue_url your user can open to keep chatting with Paige. Never submit a user's contact details without their explicit consent. Two tiers: /tools/listings returns raw structured listings in ~1s with no AI turn (rate limit 120 req/min/IP) — use it when you will do the reasoning yourself; /ask runs a live Paige turn, typical latency 3-12s, up to ~40s on heavy follow-ups — use a 45s+ timeout and retry the same URL once on failure (conversation state persists; rate limit 30 req/min/IP).","termsOfService":"https://houseme.ai/terms-of-service","contact":{"email":"dev@houseme.ai","url":"https://houseme.ai/for-ai-agents"}},"servers":[{"url":"https://houseme.ai"}],"paths":{"/tools/listings":{"get":{"operationId":"searchListings","summary":"Instant structured listing search — no AI turn, ~1s, cannot time out","description":"Deterministic query over live active listings. Fastest path when the calling agent will reason over raw data itself. Responses include ready-to-fetch links (next_page, sort variants) — fetch those literal URLs for pagination and re-sorting. Carry the attribution string when displaying listings.","parameters":[{"name":"market","in":"query","schema":{"type":"string","enum":["ca","us"]},"description":"ca = Ontario/Toronto (default), us = DC/Maryland/Virginia."},{"name":"city","in":"query","schema":{"type":"string"},"description":"City name, e.g. Rockville, Mississauga. city OR zip is required."},{"name":"zip","in":"query","schema":{"type":"string"},"description":"US 5-digit zip. city OR zip is required."},{"name":"type","in":"query","schema":{"type":"string","enum":["detached","townhouse","condo"]},"description":"Semi-detached homes are classified under detached. Responses echo this same vocabulary in each listing's 'type'."},{"name":"min_price","in":"query","schema":{"type":"number"}},{"name":"max_price","in":"query","schema":{"type":"number"}},{"name":"beds_min","in":"query","schema":{"type":"number"}},{"name":"baths_min","in":"query","schema":{"type":"number"}},{"name":"sqft_min","in":"query","schema":{"type":"number"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","price_asc","price_desc"]},"description":"Default newest."},{"name":"limit","in":"query","schema":{"type":"number","maximum":50},"description":"Default 20, max 50."},{"name":"offset","in":"query","schema":{"type":"number"},"description":"Pagination — pass the response's next_offset."},{"name":"cb","in":"query","schema":{"type":"string"},"description":"No-op cache buster — any value; use to defeat a stale client-side fetch cache. Unknown parameters are always ignored, never rejected."}],"responses":{"200":{"description":"Matching active listings with attribution and ready-to-fetch next-step links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsResponse"}}}},"400":{"description":"Missing city/zip — body is a self-describing schema with a copy-paste example."},"429":{"description":"Rate limited (120 req/min/IP)."}}}},"/ask":{"get":{"operationId":"askPaige","summary":"Ask a real-estate question in natural language","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"The question, plain English."},{"name":"market","in":"query","schema":{"type":"string","enum":["ca","us"]},"description":"ca = Ontario/Toronto (default), us = DC/Maryland/Virginia."},{"name":"c","in":"query","schema":{"type":"string"},"description":"conversation_id from a prior response — continues the thread with full context."},{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]},"description":"Markdown (default) or JSON."}],"responses":{"200":{"description":"Paige's answer. Markdown (text/markdown) by default; JSON when format=json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}},"text/markdown":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited (30 req/min/IP)."}}}},"/ask/{slug}":{"get":{"operationId":"askPaigeBySlug","summary":"Same as /ask, question in the URL path (survives query-string-stripping fetch tools)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The question as a slug: 2-bed-condo-toronto-under-650k"}],"responses":{"200":{"description":"Markdown answer.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/ask/c/{cid}/{slug}":{"get":{"operationId":"askPaigeFollowUp","summary":"Path-borne follow-up on an existing conversation","parameters":[{"name":"cid","in":"path","required":true,"schema":{"type":"string"},"description":"conversation_id from a prior response."},{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The follow-up question as a slug."}],"responses":{"200":{"description":"Markdown answer with full conversation context.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ListingsResponse":{"type":"object","properties":{"count":{"type":"number","description":"Listings returned in this page."},"total_matched":{"type":"number","description":"Listings matching ALL filters (across pages)."},"next_offset":{"type":"number","description":"Present when more pages remain — pass as offset."},"sort":{"type":"string"},"listings":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"price":{"type":"number"},"beds":{"type":"number"},"baths":{"type":"number"},"sqft":{"type":"number"},"type":{"type":"string","description":"Canonical: detached | townhouse | condo."},"type_raw":{"type":"string","description":"The board's raw label."},"days_on_market":{"type":"number"},"brokerage":{"type":"string"},"url":{"type":"string","description":"Human-viewable listing page."},"photo":{"type":"string"}}}},"attribution":{"type":"string","description":"Required data-source notice — include when displaying listings."},"links":{"type":"object","description":"Ready-to-fetch literal URLs: next_page, sort_price_asc, sort_price_desc, sort_newest, chat_with_paige."}}},"AskResponse":{"type":"object","properties":{"reply":{"type":"string","description":"Paige's answer."},"listings":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"price":{"type":"number"},"beds":{"type":"number"},"baths":{"type":"number"},"status":{"type":"string"},"url":{"type":"string","description":"Human-viewable listing page."}}}},"conversation_id":{"type":"string"},"continue_url":{"type":"string","description":"Share with your user — opens the live Paige chat with full history."}}}}}}