For developers & AI agents

Habio API & agent docs

Habio is an AI-first international property portal. You're welcome to search and read our published listings and area guides — and to submit buyer enquiries — through the endpoints below. Read endpoints need no API key. Machine-readable versions of this page live at /openapi.json and /agents.md.

MCP server (recommended)

A read-only Model Context Protocol server (JSON-RPC 2.0 over HTTP POST) at /api/mcp. Discovery card: /.well-known/mcp/server-card.json. Tools: search_properties, get_listing, search_locations.

curl -X POST https://habio.ai/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_properties",
                 "arguments":{"query":"sea view 3 bed villa in the Algarve under 600k","limit":5}}}'

Search API (REST)

POST /api/search/instant is the simplest call — deterministic, one JSON response:

curl -X POST https://habio.ai/api/search/instant \
  -H 'content-type: application/json' \
  -d '{"prompt":"3 bed apartment near the beach in the Algarve under 600k"}'

POST /api/search adds LLM intent parsing and semantic ranking. It streams NDJSON: a fast frame first, then a refined frame — read line by line and prefer the last refined frame.

Buyer enquiries

Send a buyer lead about a listing to its agent with POST /api/enquiries.

curl -X POST https://habio.ai/api/enquiries \
  -H 'content-type: application/json' \
  -d '{"listingId":"<uuid>","name":"Jane Buyer",
       "email":"[email protected]","message":"Is this still available?"}'

Rate limits

Per IP. On a 429, honour the Retry-After header. Please send a descriptive User-Agent.

Endpoint	Limit
POST /api/search	30 / minute
POST /api/search/instant	120 / minute
POST /api/mcp	60 / minute
POST /api/enquiries	5 / minute

Reference

/openapi.json — full OpenAPI 3.1 contract
/agents.md — short agent brief
/llms.txt — curated site index for LLMs
/sitemap.xml — every page and listing

Questions or higher limits? Email [email protected].