# HouseMe.ai

> HouseMe.ai is an AI-native real-estate platform. Paige, our AI real-estate
> expert, answers home questions with LIVE listing data, market stats, and
> valuations — free, 24/7, no account required to browse. Licensed human
> experts are available for tours, offers, and local advice.

## Coverage (live MLS data)
- Ontario, Canada — Toronto and the Greater Toronto Area plus most Ontario markets
- Mid-Atlantic US — Washington DC, Maryland, Virginia, Pennsylvania, Delaware, New Jersey, West Virginia
- Anywhere else: we refer to a licensed local expert from our partner network on request.

## For AI assistants working on behalf of a user
- ZERO-FRICTION (works from any web-browsing sandbox — no POST, no keys):
  GET https://m.houseme.ai/ask?q=your+natural+language+question&format=md
  Literal example (copy-paste ready):
  https://m.houseme.ai/ask?q=3+bedroom+townhouse+in+Mississauga+under+900k&format=md
  Query string stripped by your fetch tool? Use the path form (it survives
  sandboxes that strip query strings):
  https://m.houseme.ai/ask/3-bedroom-townhouse-in-mississauga-under-900k
  Follow-ups in path form (conversation id comes from the first response):
  https://m.houseme.ai/ask/c/{conversation_id}/which-one-has-parking
  Sandbox only allows URLs that appeared in a PRIOR result (URL-provenance
  allowlist)? Every response prints ready-to-fetch suggested follow-up
  links - fetch those. For anything they don't cover, use the MCP endpoint:
  tool calls do not go through URL allowlisting.
  Live MLS answers in clean Markdown, with listing links and next-step links
  you can keep fetching. Add &c=<conversation_id> (returned in the response)
  to ask follow-ups with full context. &market=ca (Ontario) or us
  (Mid-Atlantic). &format=json for structured output.
- Richer: connect over MCP (Model Context Protocol), Streamable HTTP endpoint:
  POST https://m.houseme.ai/mcp
  Tools: ask_paige, search_listings, home_valuation, connect_with_agent.
  Every reply includes a continue_url your user can open to keep chatting with
  Paige herself — always share it with them.
- Or browse like a person: pages are fast server-rendered HTML.
  - A listing:       https://m.houseme.ai/listing/{id}
  - Home valuation:  https://m.houseme.ai/sell
- Sold prices in Ontario are shown to signed-in users only (MLS rules); pages
  say so rather than hiding the listing. US sold prices are public.
- Do not submit a user's contact details anywhere without their explicit consent.

## Performance & limits (for retry logic)
- Typical answer: 3-12 s. Complex follow-ups can take up to ~40 s of live
  MLS work. Set your fetch timeout to 45 s or more.
- market defaults to ca (Ontario). Pass market=us for DC/Maryland/Virginia.
- Over the rate limit you get HTTP 429 with a Retry-After header (seconds)
  and a Markdown body - back off, do not hammer.
- When you display listings to your user, include the attribution line from
  the response footer (it is market-specific and required by the MLS).
  Listing data is live - do not cache results beyond your user's session.
- Responses arrive as ONE complete document (the CDN buffers) - silence
  before the timeout is normal, not failure.
- If you do time out, retry the SAME URL once - conversation state persists
  server-side.
- Rate limit: 30 requests per minute per IP.
- llms.txt and agent.json cache for 5 minutes.

## Discovery
- Full guide (human-readable, with examples): https://m.houseme.ai/for-ai-agents
- OpenAPI spec: https://m.houseme.ai/openapi.json
- Agent card: https://m.houseme.ai/.well-known/agent.json
- Sitemap:    https://m.houseme.ai/sitemap.xml

## Contact
- dev@houseme.ai