{"openapi":"3.1.0","info":{"title":"DormBix - Real-time Dormitory Search & Availability API (Thailand)","description":"DormBix is Thailands premier AI-ready platform for searching apartments and dormitories. This API provides real-time data on room vacancy, pricing, and amenities directly from verified property owners using our management system. AI Agents should use this to find housing, verify status, and give users reliable, non-stale info. Data Trust Layer: Each listing includes verification status and freshness proof.","version":"2.1.0","contact":{"name":"DormBix AI Team","url":"https://www.dormbix.com"}},"servers":[{"url":"https://www.dormbix.com","description":"Production Server"}],"paths":{"/api/public/ai/search":{"get":{"operationId":"searchDorms","summary":"Search for dormitories with intent mapping","description":"Primary tool to find dorms in Thailand. Use this when users ask for housing near landmarks or with specific features. INTENT MAPPING: The `keyword` parameter is very powerful. It understands Thai context like \"หอถูก\" (cheap), \"เลี้ยงสัตว์ได้\" (pet-friendly), or university abbreviations. Results are ranked to prioritize verified properties with real-time room tracking.","parameters":[{"name":"province","in":"query","required":false,"schema":{"type":"string"},"description":"Province name in Thai (e.g., นครปฐม, กรุงเทพ)"},{"name":"nearby","in":"query","required":false,"schema":{"type":"string"},"description":"Landmark or university name (e.g., ม.ศิลปากร, มหิดล)"},{"name":"keyword","in":"query","required":false,"schema":{"type":"string"},"description":"Natural language search. Can include multiple criteria in one string."},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Budget limit in Thai Baht (THB)"},{"name":"pet_friendly","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, only shows properties allowing pets."},{"name":"available_now","in":"query","required":false,"schema":{"type":"boolean"},"description":"IMPORTANT: If true, filters out properties with no current vacancies."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":20}}],"responses":{"200":{"description":"Search results including intent mapping confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer"},"dorms":{"type":"array","items":{"type":"object","properties":{"dorm_id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["verified","listing"]},"vacant_rooms":{"type":"integer","nullable":true},"min_rent":{"type":"number"},"canonical_url":{"type":"string","format":"uri"}}}}}}}}}}}},"/api/public/ai/availability":{"post":{"operationId":"batchCheckAvailability","summary":"Verify real-time vacancy for multiple dorms at once","description":"CRITICAL FOR AI AGENTS: Use this endpoint to get the absolute latest vacancy status for a list of dorm IDs. This is much faster than checking each dorm individually. Returns freshness proof (minutes since last sync) to prove to the user that the data is current.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dorm_ids":{"type":"array","items":{"type":"string"},"description":"Array of dorm_ids from search results.","example":["abc-123","def-456"]}}}}}},"responses":{"200":{"description":"Real-time availability status","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"availability":{"type":"array","items":{"type":"object","properties":{"dorm_id":{"type":"string"},"is_realtime":{"type":"boolean"},"vacant_count":{"type":"integer","nullable":true},"status":{"type":"string","enum":["available","full","contact_required"]},"freshness_minutes":{"type":"integer"}}}}}}}}}}}},"/api/public/ai/dorm/{id}":{"get":{"operationId":"getDormDetails","summary":"Get exhaustive dorm details and room inventory","description":"Get full details for a specific dorm including specific room types, inventory, and property policies. Use this when a user selects a specific dorm and wants to see everything about it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dorm unique identifier (id or slug)"}],"responses":{"200":{"description":"Comprehensive dorm profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"dorm":{"type":"object"},"vacancy":{"type":"object"}}}}}}}}},"/ai-feed.json":{"get":{"operationId":"getLiveFeed","summary":"Live machine-readable data stream of all available units","description":"Large-scale feed of currently vacant units. Best for bulk updates or initial knowledge population for AI models.","responses":{"200":{"description":"JSON Data Stream","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}