{ "openapi": "3.1.0", "info": { "title": "ChatHome Public Read API", "version": "1.2.0", "summary": "Anonymous, read-only access to Grande Région property search and Luxembourg market data.", "description": "Every endpoint in this document answers WITHOUT an account, an API key, or an OAuth token.\n\nEverything that writes — sending an inquiry to an agency, saving a document, anything user-specific — is deliberately NOT in this spec and requires authentication. The authenticated surface is documented at /mcp.\n\nRequests are rate limited per source IP. Model-backed calls (vibe search) are bounded far more tightly than plain reads; exceeding a limit returns 429 with a retry hint. Authenticate for a higher allowance.\n\nAn MCP server covering the same capabilities lives at /api/mcp, with its manifest at /.well-known/mcp.json. Its public search, listing-card, listing-detail, and market-context tools are callable anonymously too.\n\nListing facts come from the agencies' own pages and carry source evidence; a fact we cannot evidence is returned as unknown rather than guessed. Ranking is by relevance and listing quality — paid placement does not exist.", "contact": { "name": "ChatHome", "url": "https://chathome.lu/en/mission" }, "license": { "name": "Terms of use", "url": "https://chathome.lu/en/legal/terms" } }, "servers": [ { "url": "https://chathome.lu", "description": "Production" } ], "tags": [ { "name": "Search", "description": "Find properties." }, { "name": "Listings", "description": "Read one property." }, { "name": "Market data", "description": "Luxembourg commune and national market intelligence." }, { "name": "Agents", "description": "MCP endpoint for AI agents." } ], "paths": { "/api/public/v1/search": { "get": { "tags": [ "Search" ], "operationId": "getSearchCapabilities", "summary": "Supported exact filters, bounds and continuation contract", "responses": { "200": { "description": "Machine-readable input schema and coverage rules", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Search" ], "operationId": "searchStructuredProperties", "summary": "Source-proven structured search; same normalized facts as MCP", "description": "Defaults to Luxembourg; includeCrossBorder opts into supported Grande Région inventory. Supply accumulated shownListingIds to exclude previously returned IDs. This continues the live bounded window, not a stable market snapshot. Counts and source freshness are explicit. Unknown fields are refused.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "description": "Response locale: en, fr, de, lu (Luxembourgish), pt (default: en; 'lb' is a deprecated alias for 'lu')", "type": "string", "enum": [ "en", "fr", "de", "lu", "pt", "lb" ] }, "commune": { "description": "Supported municipality, city quarter or village name; use resolve_location if ambiguous", "type": "string", "minLength": 1, "maxLength": 150 }, "includeCrossBorder": { "description": "Include supported Grande Région inventory; default false keeps Luxembourg-only compatibility", "type": "boolean" }, "minPrice": { "type": "number", "minimum": 0, "maximum": 100000000 }, "maxPrice": { "type": "number", "minimum": 0, "maximum": 100000000 }, "maxTotalMonthly": { "description": "Rental-only confirmed all-in monthly ceiling; missing cost evidence is excluded", "type": "number", "minimum": 0, "maximum": 100000 }, "minBeds": { "type": "integer", "minimum": 0, "maximum": 100 }, "minBathrooms": { "type": "integer", "minimum": 0, "maximum": 100 }, "minAreaSqm": { "type": "number", "minimum": 0, "maximum": 100000 }, "maxAreaSqm": { "type": "number", "minimum": 0, "maximum": 100000 }, "propertyType": { "type": "string", "enum": [ "apartment", "house", "studio", "room", "commercial", "office", "land", "multi_unit_building", "garage_parking" ] }, "furnished": { "type": "boolean", "const": true }, "petsAllowed": { "type": "boolean", "const": true }, "elevator": { "type": "boolean", "const": true }, "parkingType": { "type": "string", "enum": [ "off_street", "garage", "covered" ] }, "balcony": { "type": "boolean", "const": true }, "garden": { "type": "boolean", "const": true }, "sort": { "type": "string", "enum": [ "relevance", "newest", "price-asc", "price-desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "shownListingIds": { "description": "Already shown listing IDs, accumulated across pages. Excludes those IDs from this live result window; not a stable market snapshot.", "maxItems": 200, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "includePhotos": { "type": "boolean" }, "intent": { "type": "string", "enum": [ "rent", "buy" ] } }, "required": [ "intent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Normalized listings, constraints, coverage, ordering and continuation", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "agent-listing.v2" }, "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "string", "const": "active" }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string", "const": "EUR" }, "listingType": { "type": "string", "enum": [ "rent", "sale" ] }, "propertyType": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "country": { "anyOf": [ { "type": "string", "enum": [ "LU", "FR", "BE", "DE" ] }, { "type": "null" } ] }, "beds": { "type": [ "number", "null" ] }, "baths": { "type": [ "number", "null" ] }, "areaSqm": { "type": [ "number", "null" ] }, "energyClass": { "type": [ "string", "null" ] }, "imageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "photoUrls": { "maxItems": 5, "type": "array", "items": { "type": "string", "format": "uri" } }, "description": { "type": [ "string", "null" ] }, "pricePerSqm": { "type": [ "number", "null" ] }, "charges": { "type": [ "number", "null" ] }, "features": { "type": "array", "items": { "type": "string" } }, "agencyName": { "type": [ "string", "null" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "original_agency_listing" }, "agencyName": { "type": [ "string", "null" ] }, "listingUrl": { "type": "string", "format": "uri" }, "agencyListingId": { "type": [ "string", "null" ] }, "lastSeenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "under_offer", "unknown" ] }, "statusBasis": { "type": "string", "enum": [ "source_catalog_seen", "listing_record_active" ] }, "agencyConfirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "type", "agencyName", "listingUrl", "agencyListingId", "lastSeenAt", "status", "statusBasis", "agencyConfirmedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "rent": { "anyOf": [ { "type": "object", "properties": { "baseMonthly": { "type": [ "number", "null" ] }, "chargesMonthly": { "type": [ "number", "null" ] }, "chargesIncluded": { "type": [ "boolean", "null" ] }, "monthlyTotal": { "type": [ "number", "null" ] }, "monthlyTotalStatus": { "anyOf": [ { "type": "string", "enum": [ "known", "unknown_charges", "conflicting_charges", "invalid_price", "unknown_mandatory_recurring_fees" ] }, { "type": "null" } ] }, "knownMonthlyLowerBound": { "type": [ "number", "null" ] }, "estimatedMonthlyTotal": { "type": [ "number", "null" ] }, "estimatedMonthlyTotalIsLowerBound": { "type": [ "boolean", "null" ] }, "estimatedUtilitiesMonthly": { "type": [ "number", "null" ] }, "indicativeInsuranceMonthly": { "type": [ "number", "null" ] }, "heatingMayBeDoubleCounted": { "type": [ "boolean", "null" ] }, "firstChargeAdvance": { "type": [ "number", "null" ] }, "reportedDeposit": { "type": [ "number", "null" ] }, "deposit": { "type": [ "number", "null" ] }, "depositMaximum": { "type": [ "number", "null" ] }, "depositExceedsMaximum": { "type": [ "boolean", "null" ] }, "agencyFee": { "type": [ "number", "null" ] }, "agencyFeeBasis": { "anyOf": [ { "type": "string", "enum": [ "tenant_share", "total_commission", "unknown" ] }, { "type": "null" } ] }, "mandatoryRecurringFees": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "mandatoryRecurringFeeTotal": { "type": [ "number", "null" ] }, "mandatoryMoveInFees": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "mandatoryMoveInFeeTotal": { "type": [ "number", "null" ] }, "knownUpfrontCost": { "type": [ "number", "null" ] }, "exactUpfrontCost": { "type": [ "number", "null" ] }, "upfrontCostIsLowerBound": { "type": [ "boolean", "null" ] }, "upfrontCostIsExact": { "type": [ "boolean", "null" ] }, "unknownComponents": { "type": "array", "items": { "type": "string" } } }, "required": [ "baseMonthly", "chargesMonthly", "chargesIncluded", "monthlyTotal", "monthlyTotalStatus", "knownMonthlyLowerBound", "estimatedMonthlyTotal", "estimatedMonthlyTotalIsLowerBound", "estimatedUtilitiesMonthly", "indicativeInsuranceMonthly", "heatingMayBeDoubleCounted", "firstChargeAdvance", "reportedDeposit", "deposit", "depositMaximum", "depositExceedsMaximum", "agencyFee", "agencyFeeBasis", "mandatoryRecurringFees", "mandatoryRecurringFeeTotal", "mandatoryMoveInFees", "mandatoryMoveInFeeTotal", "knownUpfrontCost", "exactUpfrontCost", "upfrontCostIsLowerBound", "upfrontCostIsExact", "unknownComponents" ], "additionalProperties": false }, { "type": "null" } ] }, "availability": { "type": "object", "properties": { "offerStatus": { "type": "string", "enum": [ "available", "under_offer", "unknown" ] }, "availableFrom": { "type": [ "string", "null" ] }, "moveInState": { "type": [ "string", "null" ] } }, "required": [ "offerStatus", "availableFrom", "moveInState" ], "additionalProperties": false }, "property": { "type": "object", "properties": { "rooms": { "type": [ "number", "null" ] }, "floor": { "type": [ "number", "null" ] }, "totalFloors": { "type": [ "number", "null" ] }, "constructionYear": { "type": [ "number", "null" ] }, "completionYear": { "type": [ "number", "null" ] }, "landAreaSqm": { "type": [ "number", "null" ] }, "privateRoomAreaSqm": { "type": [ "number", "null" ] }, "condition": { "type": [ "string", "null" ] }, "heatingType": { "type": [ "string", "null" ] }, "heatingEnergy": { "type": [ "string", "null" ] }, "airConditioning": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "hasFloorplan": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "rentByOwner": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "colocation": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] } }, "required": [ "rooms", "floor", "totalFloors", "constructionYear", "completionYear", "landAreaSqm", "privateRoomAreaSqm", "condition", "heatingType", "heatingEnergy", "airConditioning", "hasFloorplan", "rentByOwner", "colocation" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "precision": { "type": "string", "enum": [ "exact_address", "street", "district", "commune_only", "unknown" ] }, "confidence": { "type": "string", "enum": [ "verified", "unverified", "contradicted", "unknown" ] } }, "required": [ "city", "district", "address", "postalCode", "precision", "confidence" ], "additionalProperties": false }, "history": { "type": "object", "properties": { "firstObservedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "firstObservedBasis": { "type": "string", "const": "source_listing_date_or_chathome_ingest" }, "daysListed": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "priceDropTotalEur": { "type": [ "number", "null" ] }, "lastChangedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "firstObservedAt", "firstObservedBasis", "daysListed", "priceDropTotalEur", "lastChangedAt" ], "additionalProperties": false }, "duplicates": { "type": "object", "properties": { "confirmedOtherSources": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "confirmedSourceCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "confirmedOtherSources", "confirmedSourceCount" ], "additionalProperties": false }, "amenities": { "type": "object", "properties": { "furnished": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "elevator": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "parking": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "balcony": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "garden": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "petsAllowed": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "stepFreeAccess": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] }, "wheelchairAccessible": { "anyOf": [ { "type": "boolean", "const": true }, { "type": "null" } ] } }, "required": [ "furnished", "elevator", "parking", "balcony", "garden", "petsAllowed", "stepFreeAccess", "wheelchairAccessible" ], "additionalProperties": false }, "fieldProvenance": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "confirmed", "estimated", "thin_sample", "stale", "context_only", "conflicted", "not_collected", "source_unavailable", "suppressed" ] }, "publisher": { "type": [ "string", "null" ] }, "method": { "type": "string", "enum": [ "source_structured", "source_text", "official_dataset", "calculation", "manual_review", "model_extraction", "model_only", "unknown" ] }, "sourceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "status", "publisher", "method", "sourceUrl", "observedAt" ], "additionalProperties": false } }, "officialScreening": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "propertyChecks": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "valueContext": { "type": "object", "properties": { "priceIntegrity": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "fairPrice": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "marketContext": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "priceIntegrity", "fairPrice", "marketContext" ], "additionalProperties": false }, "missingFields": { "type": "array", "items": { "type": "string" } }, "unknown": { "description": "Why each missingFields entry is unknown. not_in_search_result means get_listing may know it.", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_stated", "not_proven", "conflicted", "not_in_search_result" ] } }, "required": [ "field", "reason" ], "additionalProperties": false } }, "match": { "type": "object", "properties": { "allRequiredConstraintsSatisfied": { "type": [ "boolean", "null" ] }, "resultKind": { "anyOf": [ { "type": "string", "enum": [ "match", "close" ] }, { "type": "null" } ] }, "closeReasons": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "not_confirmed" }, "criterionId": { "type": "string" }, "concept": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "criterionId", "concept", "label" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "numeric" }, "criterionId": { "type": "string" }, "concept": { "type": "string" }, "field": { "type": "string" }, "expected": { "type": "number" }, "actual": { "type": "number" }, "delta": { "type": "number", "minimum": 0 }, "direction": { "type": "string", "enum": [ "over", "under" ] } }, "required": [ "kind", "criterionId", "concept", "field", "expected", "actual", "delta", "direction" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "nearby_commune" }, "askedLocalityId": { "type": "string" }, "actualLocalityId": { "type": "string" }, "askedName": { "type": "string" }, "actualName": { "type": "string" }, "distanceKm": { "type": "number", "minimum": 0, "maximum": 12 } }, "required": [ "kind", "askedLocalityId", "actualLocalityId", "askedName", "actualName", "distanceKm" ], "additionalProperties": false } ] } }, "requiredConstraints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "matched", "not_matched", "not_verified", "not_applied" ] }, "target": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "actual": { "type": [ "string", "number", "boolean", "null" ] } }, "required": [ "id", "status", "target", "actual" ], "additionalProperties": false } }, "reasons": { "maxItems": 3, "type": "array", "items": { "type": "string" } } }, "required": [ "allRequiredConstraintsSatisfied", "resultKind", "requiredConstraints", "reasons" ], "additionalProperties": false }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "hasSourceCheckedFacts": { "type": "boolean" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "matchReasons": { "maxItems": 3, "type": "array", "items": { "type": "string" } } }, "required": [ "schemaVersion", "id", "url", "title", "status", "price", "currency", "listingType", "propertyType", "city", "district", "country", "beds", "baths", "areaSqm", "energyClass", "imageUrl", "agencyName", "source", "rent", "availability", "property", "location", "history", "duplicates", "amenities", "fieldProvenance", "officialScreening", "propertyChecks", "transport", "valueContext", "missingFields", "match", "latitude", "longitude" ], "additionalProperties": {} } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Exact number of listing objects returned in this response; not the number of matches in the market." }, "countKind": { "type": "string", "const": "returned" }, "returnedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "matchingCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "matchingCountKind": { "type": "string", "enum": [ "exact", "lower_bound", "unavailable" ] }, "marketMatchingUpperBound": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "null" }, "searchExhaustive": { "type": "boolean" }, "excludedUnprovenCount": { "description": "Upstream rows omitted because public facts could not prove every requested hard filter.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string" }, "note": { "type": "string" }, "understanding": { "type": "object", "properties": { "understood": { "type": "string" }, "transaction": { "anyOf": [ { "type": "string", "enum": [ "buy", "rent" ] }, { "type": "null" } ] }, "propertyTypes": { "type": "array", "items": { "type": "string" } }, "excludedPropertyTypes": { "type": "array", "items": { "type": "string" } }, "offer": { "type": "string", "enum": [ "whole", "room", "either" ] }, "places": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string", "enum": [ "live", "work", "near", "avoid" ] }, "kind": { "type": "string" }, "country": { "anyOf": [ { "type": "string", "enum": [ "LU", "FR", "BE", "DE" ] }, { "type": "null" } ] }, "radiusKm": { "type": [ "number", "null" ] }, "force": { "type": "string", "enum": [ "dealbreaker", "must", "should", "nice" ] } }, "required": [ "name", "role", "kind", "country", "radiusKm", "force" ], "additionalProperties": false } }, "commutes": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "transit", "drive", "walk", "bike" ] }, { "type": "null" } ] }, "maxMinutes": { "type": [ "number", "null" ] }, "force": { "type": "string", "enum": [ "dealbreaker", "must", "should", "nice" ] } }, "required": [ "destination", "mode", "maxMinutes", "force" ], "additionalProperties": false } }, "checked": { "type": "array", "items": { "type": "object", "properties": { "meaning": { "type": "string" }, "needId": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": [ "number", "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "force": { "type": "string", "enum": [ "dealbreaker", "must", "should", "nice" ] } }, "required": [ "meaning", "needId", "operator", "value", "unit", "force" ], "additionalProperties": false } }, "notChecked": { "type": "array", "items": { "type": "object", "properties": { "meaning": { "type": "string" }, "force": { "type": "string", "enum": [ "dealbreaker", "must", "should", "nice" ] }, "reason": { "type": "string", "enum": [ "no_listing_fact", "fact_not_collected_yet" ] } }, "required": [ "meaning", "force", "reason" ], "additionalProperties": false } } }, "required": [ "understood", "transaction", "propertyTypes", "excludedPropertyTypes", "offer", "places", "commutes", "checked", "notChecked" ], "additionalProperties": false, "description": "What the engine understood from the request. notChecked lists wishes no returned home is confirmed to have." }, "session": { "type": "object", "properties": { "brief": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "brief" ], "additionalProperties": false }, "followUp": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "applied", "answered" ] }, "reply": { "type": "string" } }, "required": [ "outcome" ], "additionalProperties": false }, "truncated": { "type": "boolean" }, "ranking": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "degraded" ] }, "scoreKind": { "type": "string", "const": "request_fit" }, "probability": { "type": "boolean", "const": false }, "planFingerprint": { "type": "string" } }, "required": [ "status", "scoreKind", "probability" ], "additionalProperties": false }, "trust": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string", "enum": [ "low", "medium", "high", "unknown" ] }, "freshness": { "type": "string", "enum": [ "fresh", "recent", "stale", "unknown" ] }, "fallback": { "type": "boolean" }, "missingFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "sources", "confidence", "freshness" ], "additionalProperties": {} } }, "required": [ "listings", "total" ], "additionalProperties": {} } } } }, "400": { "description": "Invalid or unsupported inputs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Read budget exhausted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Search unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/public/v1/estimates": { "post": { "tags": [ "Market data" ], "operationId": "getNumericPropertyEstimate", "summary": "Numeric Luxembourg estimate without an AI-written report", "description": "Uses the existing model-only public path. No free-text extraction, synthesis, caller owner ID or report control is accepted. Explicit false and zero are preserved; source age is unknown unless supplied by the source. For an authenticated full report, see /api/agent/v1/openapi.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "commune": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "propertyType": { "type": "string", "enum": [ "apartment", "house", "studio", "land" ] }, "listingType": { "type": "string", "enum": [ "rent", "sale" ] }, "areaSqm": { "type": "number", "minimum": 1, "maximum": 10000, "description": "Living area for homes; plot area for land, in m². For land, an explicitly supplied landAreaSqm takes precedence." }, "locale": { "description": "Response locale: en, fr, de, lu (Luxembourgish), pt (default: en; 'lb' is a deprecated alias for 'lu')", "type": "string", "enum": [ "en", "fr", "de", "lu", "pt", "lb" ] }, "bedrooms": { "type": "integer", "minimum": 0, "maximum": 50 }, "bathrooms": { "type": "integer", "minimum": 0, "maximum": 50 }, "rooms": { "type": "integer", "minimum": 0, "maximum": 100 }, "landAreaSqm": { "type": "number", "minimum": 1, "maximum": 100000 }, "outdoorAreaSqm": { "type": "number", "minimum": 0, "maximum": 100000 }, "floor": { "type": "integer", "minimum": -10, "maximum": 100 }, "totalFloors": { "type": "integer", "minimum": 1, "maximum": 100 }, "constructionYear": { "type": "integer", "minimum": 1700, "maximum": 9007199254740991 }, "renovationYear": { "type": "integer", "minimum": 1700, "maximum": 9007199254740991 }, "energyClass": { "type": "string", "enum": [ "A+", "A", "B", "C", "D", "E", "F", "G", "H", "I" ] }, "buildingCondition": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "renovationMajorNeeded": { "type": "boolean" }, "hasGarage": { "type": "boolean" }, "hasParking": { "type": "boolean" }, "hasGarden": { "type": "boolean" }, "hasTerrace": { "type": "boolean" }, "hasBalcony": { "type": "boolean" }, "hasPool": { "type": "boolean" }, "hasCellar": { "type": "boolean" }, "hasLift": { "type": "boolean" }, "indoorParkingAvailable": { "type": "boolean" }, "isFurnished": { "type": "boolean" }, "parkingCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "glazing": { "type": "string", "enum": [ "single", "double", "triple" ] }, "district": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "street": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "heating": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" } }, "required": [ "commune", "propertyType", "listingType", "areaSqm" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estimate, ranges, coverage and limitations", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "property-estimate.v1" }, "status": { "type": "string", "const": "available" }, "mode": { "type": "string", "const": "numeric" }, "propertyType": { "type": "string" }, "listingType": { "type": "string", "enum": [ "rent", "sale" ] }, "commune": { "type": "string" }, "areaSqm": { "type": "number" }, "areaUnit": { "type": "string", "const": "m2" }, "currency": { "type": "string", "const": "EUR" }, "priceUnit": { "type": "string", "enum": [ "EUR", "EUR/month" ] }, "pricePerSqmUnit": { "type": "string", "enum": [ "EUR/m2", "EUR/m2/month" ] }, "estimatedPrice": { "type": "number" }, "priceRangeLow": { "type": "number" }, "priceRangeHigh": { "type": "number" }, "estimatedPricePerSqm": { "type": [ "number", "null" ] }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "valuationBasis": { "type": "string", "enum": [ "commune_average", "model_estimate", "market_reference", "not_disclosed" ] }, "priceBasis": { "type": "string", "const": "asking_prices_not_completed_sales" }, "limitations": { "type": "string" }, "locationPrecision": { "type": "string" }, "locationResolution": { "type": "object", "properties": {}, "additionalProperties": {} }, "roughEstimate": { "type": "boolean" }, "usedModelPrice": { "type": "boolean" }, "communeAverageAdverts": { "type": "number" }, "sampleSize": { "type": [ "number", "null" ] }, "priceRangeCoverage": { "type": "number" }, "priceRangeWideLow": { "type": "number" }, "priceRangeWideHigh": { "type": "number" }, "priceRangeWideCoverage": { "type": "number" }, "assumptions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "drivers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "clarificationQuestions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "transactionAnchor": { "type": "object", "properties": {}, "additionalProperties": {} }, "sourceObservedAt": { "type": [ "string", "null" ] }, "calculatedAt": { "type": [ "string", "null" ] }, "trust": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string", "enum": [ "low", "medium", "high", "unknown" ] }, "freshness": { "type": "string", "enum": [ "fresh", "recent", "stale", "unknown" ] }, "fallback": { "type": "boolean" }, "missingFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "sources", "confidence", "freshness" ], "additionalProperties": {} } }, "required": [ "schemaVersion", "status", "mode", "propertyType", "listingType", "commune", "areaSqm", "areaUnit", "currency", "priceUnit", "pricePerSqmUnit", "valuationBasis", "priceBasis", "limitations", "locationResolution", "sourceObservedAt", "calculatedAt", "trust" ], "additionalProperties": {} } } } }, "400": { "description": "Invalid or unsupported inputs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Property is outside model coverage", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Estimate budget exhausted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Price model unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/public/v1/geo/resolve": { "get": { "tags": [ "Market data" ], "operationId": "resolveLocation", "summary": "Resolve supported place names, aliases or official locality IDs without guessing", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 150 } }, { "name": "country", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "LU", "FR", "BE", "DE" ] } }, { "name": "locale", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Response locale: en, fr, de, lu (Luxembourgish), pt (default: en; 'lb' is a deprecated alias for 'lu')", "type": "string", "enum": [ "en", "fr", "de", "lu", "pt", "lb" ] } } ], "responses": { "200": { "description": "Resolved location, ambiguous candidates or unknown; municipality centres are explicitly labelled", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "location-resolution.v1" }, "query": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string", "enum": [ "resolved", "ambiguous", "unknown" ] }, "resolution": { "type": "string" }, "location": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "geographyVersion": { "type": "string" }, "limitation": { "type": "string" } }, "required": [ "schemaVersion", "query", "locale", "status", "resolution", "location", "candidates", "geographyVersion", "limitation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/commute-matrix": { "get": { "tags": [ "Market data" ], "operationId": "getCommuteEstimate", "summary": "Municipality-centre travel scenario to one of six Luxembourg hubs", "description": "Country defaults to LU. Set FR, BE or DE for supported cross-border origins. Read source, computedAt, travelScenario, fare and locationResolution. Missing routes remain unavailable. These are not exact routes from a home's door.", "parameters": [ { "name": "commune", "in": "query", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 150 } }, { "name": "country", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "LU", "FR", "BE", "DE" ] } }, { "name": "destination", "in": "query", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "lux-gare", "kirchberg", "cloche-dor", "lux-city", "belval", "findel" ] } }, { "name": "mode", "in": "query", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "driving", "transit", "cycling", "walking" ] } } ], "responses": { "200": { "description": "Available route and scenario qualifications", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Place or route not covered", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Current route unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/public/v1/listings/{id}/intelligence": { "get": { "tags": [ "Listings" ], "operationId": "getListingIntelligence", "summary": "Full public listing evidence for assistants, with JSON, Markdown or a ready-to-paste review", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "locale", "in": "query", "required": false, "description": "Language for sourced page text and the review prompt", "schema": { "type": "string", "enum": [ "en", "fr", "de", "lu", "pt" ], "default": "en" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "markdown", "review" ], "default": "json" } } ], "responses": { "200": { "description": "The same public evidence as MCP get_listing. Section presence does not imply all fields are known. No model call or account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "listing", "listingPage", "listingPageContext", "pageText", "listingTools", "sectionPresence", "links", "trust" ], "properties": { "schemaVersion": { "type": "string", "const": "listing-intelligence.v1" }, "listing": { "type": "object", "description": "AgentListing v2: numeric EUR prices, monthly/annual cost fields, source evidence, location precision and explicit unknowns.", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "const": "active" }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string", "const": "EUR" }, "areaSqm": { "type": [ "number", "null" ] }, "source": { "type": [ "object", "null" ], "properties": { "listingUrl": { "type": "string" }, "lastSeenAt": { "type": [ "string", "null" ] } } }, "location": { "type": "object", "properties": { "precision": { "type": "string", "enum": [ "exact_address", "street", "district", "commune_only", "unknown" ] }, "address": { "type": [ "string", "null" ] } } }, "rent": { "type": [ "object", "null" ], "properties": { "monthlyTotal": { "type": [ "number", "null" ] }, "knownMonthlyLowerBound": { "type": [ "number", "null" ] }, "exactUpfrontCost": { "type": [ "number", "null" ] }, "unknownComponents": { "type": "array", "items": { "type": "string" } } } }, "missingFields": { "type": "array", "items": { "type": "string" } }, "fieldProvenance": { "type": "object", "additionalProperties": true }, "propertyChecks": { "type": [ "object", "null" ] }, "transport": { "type": [ "object", "null" ] } }, "additionalProperties": true }, "listingPage": { "type": "object", "additionalProperties": true, "description": "Fail-closed public listing record; no internal or user-specific data." }, "listingPageContext": { "type": [ "object", "null" ], "properties": { "priceHistory": { "type": [ "object", "null" ] }, "priceEvolution": { "type": [ "object", "null" ] }, "familyAmenities": { "type": [ "object", "null" ] }, "neighborhoodFacts": { "type": [ "object", "null" ] }, "countryEvidence": { "type": [ "object", "null" ] }, "transitSummary": { "type": [ "object", "null" ] }, "commuteSummary": { "type": [ "object", "null" ] }, "passport": { "type": [ "object", "null" ] }, "propertyChecks": { "type": [ "object", "null" ] }, "parcelDossier": { "type": [ "object", "null" ] }, "storedPlanning": { "type": [ "object", "null" ] }, "storedCommute": { "type": [ "object", "null" ] }, "currentSale": { "type": [ "object", "null" ] } } }, "pageText": { "type": "object", "additionalProperties": true }, "listingTools": { "type": [ "object", "null" ], "description": "Saved, dated financial examples and their completeness flags; not personal advice." }, "sectionPresence": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Payload presence only. Nested status/coverage and unknown fields determine whether any usable evidence exists." }, "links": { "type": "object", "properties": { "listing": { "type": "string", "format": "uri" }, "json": { "type": "string", "format": "uri" }, "markdown": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" } } }, "trust": { "type": "object", "additionalProperties": true } } } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid ID, language or format", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Listing not found or no longer public", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Evidence temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/public/v1/calculations/mortgage": { "post": { "tags": [ "Market data" ], "operationId": "calculateMortgage", "summary": "Stateless mortgage calculation using explicit assumptions; no account or saved scenario", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "principal": { "type": "number", "minimum": 0, "maximum": 50000000, "description": "Loan principal in EUR, after the down payment; excludes acquisition costs unless explicitly financed" }, "annualRatePct": { "type": "number", "minimum": 0, "maximum": 30, "description": "Explicit annual interest-rate assumption in percent; do not invent a current bank quote" }, "years": { "type": "integer", "minimum": 1, "maximum": 40, "description": "Repayment term in years" }, "extraMonthlyPayment": { "default": 0, "type": "number", "minimum": 0, "maximum": 100000 }, "includeSchedule": { "default": false, "description": "Include the month-by-month schedule only when requested", "type": "boolean" } }, "required": [ "principal", "annualRatePct", "years" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Loan payment and interest, not an all-in housing budget", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "mortgage-scenario.v1" }, "currency": { "type": "string", "const": "EUR" }, "inputs": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "principal": { "type": "number", "minimum": 0, "maximum": 50000000, "description": "Loan principal in EUR, after the down payment; excludes acquisition costs unless explicitly financed" }, "annualRatePct": { "type": "number", "minimum": 0, "maximum": 30, "description": "Explicit annual interest-rate assumption in percent; do not invent a current bank quote" }, "years": { "type": "integer", "minimum": 1, "maximum": 40, "description": "Repayment term in years" }, "extraMonthlyPayment": { "default": 0, "type": "number", "minimum": 0, "maximum": 100000 }, "includeSchedule": { "default": false, "description": "Include the month-by-month schedule only when requested", "type": "boolean" } }, "required": [ "principal", "annualRatePct", "years", "extraMonthlyPayment", "includeSchedule" ], "additionalProperties": false }, "rateBasis": { "type": "string", "const": "user_assumption" }, "monthlyPayment": { "type": "number" }, "extraMonthlyPayment": { "type": "number" }, "totalInterest": { "type": "number" }, "totalRepaid": { "type": "number" }, "repaymentMonths": { "type": "integer" }, "excludedCosts": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "schedule": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid calculation inputs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/financial-tools/rates": { "get": { "tags": [ "Market data" ], "operationId": "getMortgageRates", "summary": "Source-dated public mortgage observations; availability and fixing periods must be respected", "responses": { "200": { "description": "Published rate feed; official initial-fixation bands are not full-term fixed quotes", "content": { "application/json": { "schema": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "available", "unavailable" ] }, "dataStatus": { "type": "string" }, "bankExamples": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "bankReferenceEdition": { "type": [ "string", "null" ] }, "officialRates": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "503": { "description": "Rates unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/search": { "post": { "tags": [ "Search" ], "operationId": "searchProperties", "summary": "Search properties for rent or for sale", "description": "Natural-language (vibe) or structured (classic) property search across supported Grande Région inventory. Vibe mode uses an LLM plan plus embeddings and is rate limited more tightly than classic mode. Send the searcher's own words; the engine handles vague and partial queries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "vibe", "classic" ], "description": "\"vibe\" is natural-language search (LLM plan + embeddings). \"classic\" is structured filtering with no model call." }, "query": { "type": "string", "maxLength": 800, "description": "The searcher's own words, for example: quiet 2-bed near Kirchberg with a balcony under 2000. Required for vibe mode; longer text is truncated at 800 characters." }, "intent": { "type": "string", "enum": [ "rent", "buy" ], "default": "rent", "description": "Whether to search rentals or properties for sale." }, "lang": { "type": "string", "enum": [ "en", "fr", "de", "lu", "pt" ], "default": "en", "description": "Response language." }, "limit": { "type": "integer", "minimum": 1, "maximum": 120, "default": 24, "description": "Results to return. Anonymous callers are capped at 120 (200 for map requests)." }, "includeCrossBorder": { "type": "boolean", "default": true, "description": "The Grande Région is the default market. Send false to restrict to Luxembourg." }, "filters": { "type": "object", "additionalProperties": true, "description": "Structured filters for classic mode (location, price bounds, bedrooms, property type). Unknown keys are reported back in `ignoredFilters` rather than rejected." } } }, "examples": { "vibe": { "summary": "Natural language", "value": { "mode": "vibe", "intent": "rent", "query": "quiet 2-bedroom apartment near Kirchberg with a balcony under 2500", "lang": "en", "limit": 10 } }, "classic": { "summary": "Structured filters", "value": { "mode": "classic", "intent": "buy", "lang": "en", "limit": 24, "filters": { "location": "esch-sur-alzette", "bedrooms": 3 } } } } } } }, "responses": { "200": { "description": "Search outcome. Check `status` before reading `results`.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Search outcome. The engine returns additional diagnostic fields (run report, per-result criterion checks, match summary) not described here.", "properties": { "status": { "type": "string", "enum": [ "ok", "irrelevant", "needs_clarification", "needs_refinement", "search_unavailable", "error" ], "description": "\"ok\" means results were served. \"needs_refinement\" and \"needs_clarification\" mean the request could not be compiled into a search the engine can prove, and NO listings are returned — an empty list in that state is not a claim that the market is empty." }, "searchRequestId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "description": "A property result. More fields are returned than are listed here; treat the object as open.", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Listing id, stable across requests." }, "title": { "type": "string" }, "description": { "type": "string", "description": "Short snippet of the agency's own copy." }, "price": { "type": "string", "description": "Preformatted whole-euro display string, e.g. \"EUR 1,850\". Never cents." }, "priceAmount": { "type": [ "integer", "null" ], "description": "Asking amount in whole euros, or null for price-on-request. Prefer this over parsing `price`." }, "location": { "type": "string" }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code." }, "image": { "type": [ "string", "null" ], "format": "uri" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "matchScore": { "type": [ "number", "null" ], "description": "Relevance 0-100 for vibe searches, or null when there is no query-relevant signal to score." }, "specs": { "type": "object", "additionalProperties": true, "properties": { "beds": { "type": [ "integer", "null" ] }, "baths": { "type": [ "integer", "null" ] }, "area": { "type": [ "number", "null" ], "description": "Living area in m²." }, "landAreaSqm": { "type": [ "number", "null" ] } } }, "tags": { "type": "array", "items": { "type": "string" } }, "listingType": { "type": "string" }, "explanation": { "type": "object", "additionalProperties": true, "description": "Why this listing matched, when the engine can say." } }, "required": [ "id", "title", "price", "location" ] } }, "resolvedIntent": { "type": "string", "enum": [ "rent", "buy" ] }, "brief": { "type": "object", "additionalProperties": true, "description": "Vibe mode: the typed reading of the request the search ran on — places, commutes, needs bound to listing facts, and `unmapped` wishes that were not checked. Send it back as `brief` to re-run it without a new reading." }, "coverageNotice": { "type": "object", "additionalProperties": true, "description": "What the search could NOT cover, when applicable." }, "ignoredFilters": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Filters we could not honour, named rather than swallowed." } }, "required": [ "status" ] } } } }, "400": { "description": "Missing or invalid query.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit exceeded. Retry later or authenticate.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Search index is not ready.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/listings/public/{id}": { "get": { "tags": [ "Listings" ], "operationId": "getPublicListing", "summary": "Get one listing's public facts", "description": "Source-checked public facts for a single property, with gallery photos and the canonical chathome.lu URL. Facts without source evidence are returned as unknown rather than guessed.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Listing id (letters, digits, hyphen, underscore).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "lang", "in": "query", "required": false, "description": "Translate the listing copy into this language.", "schema": { "type": "string", "enum": [ "en", "fr", "de", "lu", "pt" ] } } ], "responses": { "200": { "description": "The listing.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "listingType": { "type": [ "string", "null" ] }, "location": { "type": [ "object", "null" ], "properties": { "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "signedImages": { "type": "array", "items": { "type": "string" } } }, "description": "Listing document: identity, price, specs, location, images, agency contact target, and per-fact source evidence." } } } }, "400": { "description": "Malformed listing id.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "No data for this identifier.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/public/v1/communes": { "get": { "tags": [ "Market data" ], "operationId": "listCommunes", "summary": "List Luxembourg communes", "description": "Every Luxembourg commune with slug, localized name, and liveability score. Cached one hour.", "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "Language for commune names.", "schema": { "type": "string", "enum": [ "en", "fr", "de", "lu", "pt" ], "default": "en" } } ], "responses": { "200": { "description": "Commune list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "communes": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "liveabilityScore": { "type": [ "number", "null" ] }, "liveabilityScoreStatus": { "type": [ "string", "null" ] } }, "required": [ "slug" ] } }, "total": { "type": "integer" }, "locale": { "type": "string" }, "liveabilityAvailability": { "type": "string", "enum": [ "unavailable" ], "description": "Present when the static commune registry is returned because live intelligence is unavailable; all liveability scores then stay null." } }, "required": [ "communes", "total" ] } } } }, "500": { "description": "Upstream failure.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/api/public/v1/communes/{slug}/intelligence": { "get": { "tags": [ "Market data" ], "operationId": "getCommuneIntelligence", "summary": "Get market context and liveability for a commune", "description": "Market data and liveability dimensions for one commune — prices, transport, schools, amenities — with the sources each dimension rests on and when it was last updated. Same capability as the get_market_context MCP tool.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Luxembourg commune slug, e.g. \"luxembourg\", \"esch-sur-alzette\", \"differdange\".", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "Language for the summary text.", "schema": { "type": "string", "enum": [ "en", "fr", "de", "lu", "pt" ], "default": "en" } } ], "responses": { "200": { "description": "Commune intelligence.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "communeName": { "type": [ "string", "object" ] }, "liveabilityScore": { "type": [ "number", "null" ] }, "liveabilityScoreStatus": { "type": [ "string", "null" ] }, "dimensions": { "type": "object", "additionalProperties": true }, "summary": { "type": [ "string", "null" ] }, "lastUpdated": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Missing commune slug.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] } } } }, "404": { "description": "No data for this identifier.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/api/public/v1/market-index": { "get": { "tags": [ "Market data" ], "operationId": "getMarketIndex", "summary": "Get the latest published Luxembourg Price Index issue", "description": "The most recent published issue of the Luxembourg Price Index. Methodology is documented at /en/prices/methodology.", "responses": { "200": { "description": "Latest index issue.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "sourceIssueId": { "type": "string" }, "month": { "type": "string" }, "saleMedianPerSqm": { "type": [ "number", "null" ] }, "rentMedianPerSqm": { "type": [ "number", "null" ] }, "saleSampleSize": { "type": "integer" }, "rentSampleSize": { "type": "integer" }, "activeListingCount": { "type": "integer" }, "communeCount": { "type": "integer" }, "computedAt": { "type": "string" }, "publishedAt": { "type": "string" }, "methodologyVersion": { "type": "string" }, "methodologyUrl": { "type": "string", "format": "uri" }, "canonicalUrl": { "type": "string", "format": "uri" } } } } } }, "404": { "description": "No published issue yet.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] } } } } } } }, "/api/public/v1/national-indicators": { "get": { "tags": [ "Market data" ], "operationId": "getNationalIndicators", "summary": "Get official national housing and energy indicators", "description": "Housing-price and energy-price indicators published by the national statistical authority of France, Germany, or Belgium, and the Eurostat national house-price index for Luxembourg. Luxembourg has a housing indicator only: its energy field is always null.", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country code.", "schema": { "type": "string", "enum": [ "FR", "DE", "BE", "LU" ] } }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "housing", "energy" ], "default": "all" } } ], "responses": { "200": { "description": "Indicator bundle.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "country": { "type": "string" }, "housing": { "type": [ "object", "null" ] }, "energy": { "type": [ "object", "null" ] } } } } } }, "400": { "description": "Unsupported country or topic.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "No data for this identifier.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] } } } }, "503": { "description": "Indicator store temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/mcp": { "post": { "tags": [ "Agents" ], "operationId": "callMcp", "summary": "MCP endpoint (JSON-RPC 2.0 over Streamable HTTP)", "description": "Model Context Protocol server. Not a REST endpoint — the body is a JSON-RPC 2.0 message.\n\nWith no credential you can run the handshake (initialize, tools/list, ping) and the complete public property journey: search_vibe, search_rentals, search_for_sale, render_listing_cards, get_listing, and get_market_context. Anonymous calls are capped per source IP, and model-backed calls also share one global hourly budget.\n\nEvery other tool — and everything that writes or is user-specific — requires an API key (X-API-Key) or an OAuth 2.1 token, and answers 401 with WWW-Authenticate. Manifest: /.well-known/mcp.json.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } }, "required": [ "jsonrpc", "method" ] }, "examples": { "anonymousVibeSearch": { "summary": "Anonymous vibe search", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_vibe", "arguments": { "query": "family house with a garden near Belval", "intent": "rent", "limit": 5 } } } } } } } }, "responses": { "200": { "description": "JSON-RPC result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "This tool requires a credential. Carries WWW-Authenticate.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "schemas": { "PublicApiError": { "type": "object", "description": "Standard public-API error envelope used by /api/public/v1 routes.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMIT_EXCEEDED", "UNAUTHORIZED", "NOT_FOUND", "BAD_REQUEST", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "status": { "type": "integer" } }, "required": [ "error" ] }, "ListingCard": { "type": "object", "description": "A property result. More fields are returned than are listed here; treat the object as open.", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Listing id, stable across requests." }, "title": { "type": "string" }, "description": { "type": "string", "description": "Short snippet of the agency's own copy." }, "price": { "type": "string", "description": "Preformatted whole-euro display string, e.g. \"EUR 1,850\". Never cents." }, "priceAmount": { "type": [ "integer", "null" ], "description": "Asking amount in whole euros, or null for price-on-request. Prefer this over parsing `price`." }, "location": { "type": "string" }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code." }, "image": { "type": [ "string", "null" ], "format": "uri" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "matchScore": { "type": [ "number", "null" ], "description": "Relevance 0-100 for vibe searches, or null when there is no query-relevant signal to score." }, "specs": { "type": "object", "additionalProperties": true, "properties": { "beds": { "type": [ "integer", "null" ] }, "baths": { "type": [ "integer", "null" ] }, "area": { "type": [ "number", "null" ], "description": "Living area in m²." }, "landAreaSqm": { "type": [ "number", "null" ] } } }, "tags": { "type": "array", "items": { "type": "string" } }, "listingType": { "type": "string" }, "explanation": { "type": "object", "additionalProperties": true, "description": "Why this listing matched, when the engine can say." } }, "required": [ "id", "title", "price", "location" ] }, "SearchRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "vibe", "classic" ], "description": "\"vibe\" is natural-language search (LLM plan + embeddings). \"classic\" is structured filtering with no model call." }, "query": { "type": "string", "maxLength": 800, "description": "The searcher's own words, for example: quiet 2-bed near Kirchberg with a balcony under 2000. Required for vibe mode; longer text is truncated at 800 characters." }, "intent": { "type": "string", "enum": [ "rent", "buy" ], "default": "rent", "description": "Whether to search rentals or properties for sale." }, "lang": { "type": "string", "enum": [ "en", "fr", "de", "lu", "pt" ], "default": "en", "description": "Response language." }, "limit": { "type": "integer", "minimum": 1, "maximum": 120, "default": 24, "description": "Results to return. Anonymous callers are capped at 120 (200 for map requests)." }, "includeCrossBorder": { "type": "boolean", "default": true, "description": "The Grande Région is the default market. Send false to restrict to Luxembourg." }, "filters": { "type": "object", "additionalProperties": true, "description": "Structured filters for classic mode (location, price bounds, bedrooms, property type). Unknown keys are reported back in `ignoredFilters` rather than rejected." } } }, "SearchResponse": { "type": "object", "additionalProperties": true, "description": "Search outcome. The engine returns additional diagnostic fields (run report, per-result criterion checks, match summary) not described here.", "properties": { "status": { "type": "string", "enum": [ "ok", "irrelevant", "needs_clarification", "needs_refinement", "search_unavailable", "error" ], "description": "\"ok\" means results were served. \"needs_refinement\" and \"needs_clarification\" mean the request could not be compiled into a search the engine can prove, and NO listings are returned — an empty list in that state is not a claim that the market is empty." }, "searchRequestId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "description": "A property result. More fields are returned than are listed here; treat the object as open.", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Listing id, stable across requests." }, "title": { "type": "string" }, "description": { "type": "string", "description": "Short snippet of the agency's own copy." }, "price": { "type": "string", "description": "Preformatted whole-euro display string, e.g. \"EUR 1,850\". Never cents." }, "priceAmount": { "type": [ "integer", "null" ], "description": "Asking amount in whole euros, or null for price-on-request. Prefer this over parsing `price`." }, "location": { "type": "string" }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code." }, "image": { "type": [ "string", "null" ], "format": "uri" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "matchScore": { "type": [ "number", "null" ], "description": "Relevance 0-100 for vibe searches, or null when there is no query-relevant signal to score." }, "specs": { "type": "object", "additionalProperties": true, "properties": { "beds": { "type": [ "integer", "null" ] }, "baths": { "type": [ "integer", "null" ] }, "area": { "type": [ "number", "null" ], "description": "Living area in m²." }, "landAreaSqm": { "type": [ "number", "null" ] } } }, "tags": { "type": "array", "items": { "type": "string" } }, "listingType": { "type": "string" }, "explanation": { "type": "object", "additionalProperties": true, "description": "Why this listing matched, when the engine can say." } }, "required": [ "id", "title", "price", "location" ] } }, "resolvedIntent": { "type": "string", "enum": [ "rent", "buy" ] }, "brief": { "type": "object", "additionalProperties": true, "description": "Vibe mode: the typed reading of the request the search ran on — places, commutes, needs bound to listing facts, and `unmapped` wishes that were not checked. Send it back as `brief` to re-run it without a new reading." }, "coverageNotice": { "type": "object", "additionalProperties": true, "description": "What the search could NOT cover, when applicable." }, "ignoredFilters": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Filters we could not honour, named rather than swallowed." } }, "required": [ "status" ] }, "CommuneSummary": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "liveabilityScore": { "type": [ "number", "null" ] }, "liveabilityScoreStatus": { "type": [ "string", "null" ] } }, "required": [ "slug" ] } } }, "externalDocs": { "description": "Agent-facing overview, MCP setup, and data sources", "url": "https://chathome.lu/llms.txt" } }