{"openapi":"3.1.0","info":{"title":"Habio Public API","version":"1.0.0","summary":"Natural-language property search and lead enquiries for AI agents and assistants.","description":"Habio is an AI-first international property portal. This contract covers the public, read-mostly endpoints an agent can call directly: natural-language search over published listings, the Model Context Protocol (MCP) server, and buyer lead enquiries. No API key is required for the read endpoints. Please respect the per-endpoint rate limits and identify your bot with a descriptive User-Agent. For a curated site index see https://habio.ai/llms.txt; for MCP discovery see https://habio.ai/.well-known/mcp/server-card.json.","contact":{"name":"Habio","email":"agents@habio.ai","url":"https://habio.ai/docs"},"license":{"name":"Proprietary — see Terms","url":"https://habio.ai/terms"}},"servers":[{"url":"https://habio.ai","description":"Production"}],"externalDocs":{"description":"Human-readable API docs","url":"https://habio.ai/docs"},"tags":[{"name":"Search","description":"Natural-language search over published listings."},{"name":"MCP","description":"Model Context Protocol server (JSON-RPC 2.0)."},{"name":"Enquiries","description":"Submit a buyer lead about a listing."}],"paths":{"/api/search/instant":{"post":{"tags":["Search"],"operationId":"instantSearch","summary":"Instant (deterministic) property search","description":"Fast, rules-only search — no LLM. Returns a single JSON response, ideal for agents that want one deterministic call. Rate limit: 120 requests/minute/IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"examples":{"algarve":{"value":{"prompt":"3 bed apartment near the beach in the Algarve under 600k"}}}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstantSearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/search":{"post":{"tags":["Search"],"operationId":"search","summary":"Full AI/semantic property search (streamed)","description":"Natural-language search with LLM intent parsing + semantic (pgvector) ranking. The response is STREAMED as newline-delimited JSON (`application/x-ndjson`): a `fast` frame lands first (instant rules-only results), then a `refined` frame with the AI-ranked set. Read line by line and prefer the last `refined` frame. Rate limit: 30 requests/minute/IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"A stream of NDJSON frames; each line is a SearchFrame object.","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/SearchFrame"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/mcp":{"get":{"tags":["MCP"],"operationId":"mcpDescriptor","summary":"MCP server descriptor","description":"Returns a human/agent-readable descriptor of the MCP server (name, transport, tools). The machine discovery document is at /.well-known/mcp/server-card.json.","responses":{"200":{"description":"Server descriptor.","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["MCP"],"operationId":"mcpRpc","summary":"MCP JSON-RPC endpoint","description":"Stateless, read-only Model Context Protocol over JSON-RPC 2.0 (Streamable HTTP). Supports `initialize`, `tools/list` and `tools/call`. Tools: `search_properties` (natural-language search), `get_listing` (details by slug), `search_locations` (area guides). Rate limit: 60 requests/minute/IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"},"examples":{"toolsList":{"value":{"jsonrpc":"2.0","id":1,"method":"tools/list"}},"searchCall":{"value":{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_properties","arguments":{"query":"sea view villa in Lagos","limit":5}}}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"202":{"description":"Accepted (for JSON-RPC notifications, no body)."}}}},"/api/enquiries":{"post":{"tags":["Enquiries"],"operationId":"createEnquiry","summary":"Submit a buyer enquiry (lead) about a listing","description":"Sends a buyer enquiry to the listing's agent (and Habio). Stores a record and emails the agent. Rate limit: 5 requests/minute/IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquiryRequest"}}}},"responses":{"200":{"description":"Enquiry stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquiryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"SearchRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":8000,"description":"Natural-language description of the property being sought."}}},"Listing":{"type":"object","description":"A published property listing (summary shape returned by search).","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","description":"URL slug; use with the get_listing MCP tool."},"title":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string","examples":["EUR","GBP"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"bedrooms":{"type":["integer","null"]},"property_type":{"type":["string","null"],"examples":["apartment","house","villa","townhouse","plot"]},"images":{"type":"array","items":{"type":"string","format":"uri"}},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"lifestyle_tags":{"type":["array","null"],"items":{"type":"string"}},"ai_matched":{"type":"boolean","description":"True when the semantic pass matched this listing to the query intent."},"created_at":{"type":"string","format":"date-time"}},"required":["id","slug","title","price","currency"]},"InstantSearchResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"intent":{"type":"object","description":"Parsed search intent (country, regions, price, beds…)."},"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"resultCount":{"type":"integer"},"fallbackMode":{"type":["string","null"]},"retrievalMode":{"type":["string","null"]}},"required":["ok","listings","resultCount"]},"SearchFrame":{"type":"object","description":"One NDJSON line from POST /api/search.","properties":{"ok":{"type":"boolean"},"phase":{"type":"string","enum":["fast","refined","error"]},"intent":{"type":"object"},"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"resultCount":{"type":"integer"},"searchId":{"type":["string","null"]},"message":{"type":"string","description":"Present only on phase=error."}},"required":["ok","phase"]},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object"}}},"JsonRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"EnquiryRequest":{"type":"object","required":["name","email","message"],"properties":{"listingId":{"type":["string","null"],"format":"uuid","description":"Listing the enquiry is about."},"name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","maxLength":320},"phone":{"type":["string","null"],"maxLength":40},"message":{"type":"string","minLength":1,"maxLength":8000},"cashBuyer":{"type":"boolean"},"requiresFinancing":{"type":"boolean"}}},"EnquiryResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","format":"uuid"}},"required":["ok"]},"Error":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"message":{"type":"string"},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded. Check the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}