# Habio — Agent Guide

Habio is an AI-first international property portal. Buyers describe the life they want in plain
language and we match published homes for sale. Agents and assistants are welcome to search and
read our public data, and to submit buyer enquiries.

## Start here
- Site index (for LLMs): https://habio.ai/llms.txt
- Full content, inlined: https://habio.ai/llms-full.txt
- API contract (OpenAPI 3.1): https://habio.ai/openapi.json
- Human-readable API docs: https://habio.ai/docs
- Sitemap (all pages/listings): https://habio.ai/sitemap.xml

## MCP server (preferred for agents)
Read-only Model Context Protocol, JSON-RPC 2.0 over HTTP POST. No auth.
- Endpoint: https://habio.ai/api/mcp
- Discovery doc: https://habio.ai/.well-known/mcp.json
- Server card: https://habio.ai/.well-known/mcp/server-card.json
- Skills index: https://habio.ai/.well-known/agent-skills.json
- Tools:
  - `search_properties` — natural-language search over published listings.
  - `get_listing` — full details for one listing by slug.
  - `search_locations` — area guides (towns/regions/countries).

## REST endpoints
- `POST https://habio.ai/api/search/instant` — instant, deterministic search. Body: `{ "prompt": "..." }`. Single JSON response.
- `POST https://habio.ai/api/search` — full AI/semantic search. Body: `{ "prompt": "..." }`. Streams NDJSON (`fast` then `refined` frames).
- `POST https://habio.ai/api/enquiries` — submit a buyer enquiry about a listing. Body: `{ "listingId", "name", "email", "message", "phone?" }`.

## Auth & usage
- Read endpoints (search, MCP) need no API key.
- Please send a descriptive `User-Agent` identifying your bot.
- Public listing data may be used to answer buyer questions; please attribute Habio and link back
  to the listing/area page you cite.

## Rate limits (per IP)
- `/api/search`: 30 requests/minute
- `/api/search/instant`: 120 requests/minute
- `/api/mcp`: 60 requests/minute
- `/api/enquiries`: 5 requests/minute
Respect the `Retry-After` header on `429` responses.

## Do not crawl
/admin, /auth, /account, /saved, and non-public /api routes (see https://habio.ai/robots.txt).

## Contact
agents@habio.ai