{"openapi":"3.1.0","info":{"title":"Rafid Agent API","version":"0.1.0","description":"Property intelligence calculations in OMR for agents and applications. Use Authorize to set X-API-Key. Maintenance is an uncalibrated heuristic. Monetary outputs are rounded to two decimals. Aliases maintenance and maintenanceCost are mutually exclusive; comparison names must be unique."},"tags":[{"name":"Property","description":"Property analysis and comparison calculations."},{"name":"Maintenance","description":"Annual maintenance reserve estimation."},{"name":"Oman","description":"Oman/Muscat-specific property analysis using local rental/sale comparables, normalization, confidence scoring and provenance. Muscat governorate only; see GET /llms.txt for supported areas and data limitations."},{"name":"Agent","description":"Public discovery, pricing and tool-catalog endpoints for AI agents and agent marketplaces."},{"name":"System","description":"Public discovery, health and documentation endpoints."},{"name":"x402","description":"Pay-per-call protocol information, always available; payment-gated endpoints are settled on-chain via the x402 protocol and require no account or API key."}],"servers":[{"url":"/"}],"paths":{"/api/v1/property/analyze":{"post":{"operationId":"analyze_property","tags":["Property"],"summary":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.","description":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000}},"required":["propertyValue","annualRent"],"additionalProperties":false},"examples":{"default":{"summary":"analyze_property request","value":{"propertyValue":85000,"annualRent":7200,"serviceCharge":650,"maintenanceCost":400}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"analyze_property response","value":{"success":true,"data":{"propertyValue":85000,"annualRent":7200,"grossAnnualIncome":7200,"grossYield":8.47,"netYield":7.24,"annualOperatingCost":1050,"annualNetIncome":6150,"effectiveAnnualRent":7200,"paybackYears":13.82,"grossYieldPct":8.47,"netYieldPct":7.24,"annualOperatingCosts":1050,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."},"meta":{"requestId":"example-request","tool":"analyze_property","price":0.01,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/v1/property/analyze":{"post":{"operationId":"analyze_property_legacy","tags":["Property"],"summary":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.","description":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000}},"required":["propertyValue","annualRent"],"additionalProperties":false},"examples":{"default":{"summary":"analyze_property request","value":{"propertyValue":85000,"annualRent":7200,"serviceCharge":650,"maintenanceCost":400}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"analyze_property response","value":{"success":true,"data":{"propertyValue":85000,"annualRent":7200,"grossAnnualIncome":7200,"grossYield":8.47,"netYield":7.24,"annualOperatingCost":1050,"annualNetIncome":6150,"effectiveAnnualRent":7200,"paybackYears":13.82,"grossYieldPct":8.47,"netYieldPct":7.24,"annualOperatingCosts":1050,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."},"meta":{"requestId":"example-request","tool":"analyze_property","price":0.01,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}},"deprecated":true}},"/api/v1/property/compare":{"post":{"operationId":"compare_properties","tags":["Property"],"summary":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.","description":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["propertyValue","annualRent","name"],"additionalProperties":false}}},"required":["properties"],"additionalProperties":false},"examples":{"default":{"summary":"compare_properties request","value":{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200},{"name":"B","propertyValue":100000,"annualRent":7000}]}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"},"name":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note","name"],"additionalProperties":false}},"sortedByNetYield":{"type":"array","items":{"type":"string"}}},"required":["properties","sortedByNetYield"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"compare_properties response","value":{"success":true,"data":{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200,"grossAnnualIncome":7200,"grossYield":8.47,"netYield":8.47,"annualOperatingCost":0,"annualNetIncome":7200,"effectiveAnnualRent":7200,"paybackYears":11.81,"grossYieldPct":8.47,"netYieldPct":8.47,"annualOperatingCosts":0,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."},{"name":"B","propertyValue":100000,"annualRent":7000,"grossAnnualIncome":7000,"grossYield":7,"netYield":7,"annualOperatingCost":0,"annualNetIncome":7000,"effectiveAnnualRent":7000,"paybackYears":14.29,"grossYieldPct":7,"netYieldPct":7,"annualOperatingCosts":0,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."}],"sortedByNetYield":["A","B"]},"meta":{"requestId":"example-request","tool":"compare_properties","price":0.03,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/v1/property/compare":{"post":{"operationId":"compare_properties_legacy","tags":["Property"],"summary":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.","description":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["propertyValue","annualRent","name"],"additionalProperties":false}}},"required":["properties"],"additionalProperties":false},"examples":{"default":{"summary":"compare_properties request","value":{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200},{"name":"B","propertyValue":100000,"annualRent":7000}]}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"},"name":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note","name"],"additionalProperties":false}},"sortedByNetYield":{"type":"array","items":{"type":"string"}}},"required":["properties","sortedByNetYield"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"compare_properties response","value":{"success":true,"data":{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200,"grossAnnualIncome":7200,"grossYield":8.47,"netYield":8.47,"annualOperatingCost":0,"annualNetIncome":7200,"effectiveAnnualRent":7200,"paybackYears":11.81,"grossYieldPct":8.47,"netYieldPct":8.47,"annualOperatingCosts":0,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."},{"name":"B","propertyValue":100000,"annualRent":7000,"grossAnnualIncome":7000,"grossYield":7,"netYield":7,"annualOperatingCost":0,"annualNetIncome":7000,"effectiveAnnualRent":7000,"paybackYears":14.29,"grossYieldPct":7,"netYieldPct":7,"annualOperatingCosts":0,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."}],"sortedByNetYield":["A","B"]},"meta":{"requestId":"example-request","tool":"compare_properties","price":0.03,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}},"deprecated":true}},"/api/v1/maintenance/estimate":{"post":{"operationId":"estimate_maintenance","tags":["Maintenance"],"summary":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.","description":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"ageYears":{"type":"number","minimum":0,"maximum":200},"units":{"type":"integer","minimum":1,"maximum":10000},"annualRent":{"description":"Legacy input; unused in this value-based estimate","type":"number","minimum":0,"maximum":1000000000000},"assumptions":{"type":"object","properties":{"annualRatePct":{"type":"number","minimum":0,"maximum":100},"additionalUnitCost":{"type":"number","minimum":0,"maximum":1000000000000}},"additionalProperties":false}},"required":["propertyValue"],"additionalProperties":false},"examples":{"default":{"summary":"estimate_maintenance request","value":{"propertyValue":100000,"ageYears":12,"units":1}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"estimatedAnnualMaintenance":{"type":"number"},"monthlyReserve":{"type":"number"},"maintenancePercentage":{"type":"number"},"currency":{"type":"string","const":"OMR"},"assumptionsUsed":{"type":"object","properties":{"ageYears":{"type":"number"},"units":{"type":"number"},"annualRatePct":{"type":"number"},"additionalUnitCost":{"type":"number"}},"required":["ageYears","units","annualRatePct","additionalUnitCost"],"additionalProperties":false},"methodology":{"type":"string"}},"required":["estimatedAnnualMaintenance","monthlyReserve","maintenancePercentage","currency","assumptionsUsed","methodology"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"estimate_maintenance response","value":{"success":true,"data":{"estimatedAnnualMaintenance":1300,"monthlyReserve":108.33,"maintenancePercentage":1.3,"currency":"OMR","assumptionsUsed":{"ageYears":12,"units":1,"annualRatePct":1.3,"additionalUnitCost":35},"methodology":"Annual reserve = propertyValue * annualRatePct / 100 + (units - 1) * additionalUnitCost. Uncalibrated heuristic; excludes property type and area."},"meta":{"requestId":"example-request","tool":"estimate_maintenance","price":0.02,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/v1/maintenance/estimate":{"post":{"operationId":"estimate_maintenance_legacy","tags":["Maintenance"],"summary":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.","description":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"ageYears":{"type":"number","minimum":0,"maximum":200},"units":{"type":"integer","minimum":1,"maximum":10000},"annualRent":{"description":"Legacy input; unused in this value-based estimate","type":"number","minimum":0,"maximum":1000000000000},"assumptions":{"type":"object","properties":{"annualRatePct":{"type":"number","minimum":0,"maximum":100},"additionalUnitCost":{"type":"number","minimum":0,"maximum":1000000000000}},"additionalProperties":false}},"required":["propertyValue"],"additionalProperties":false},"examples":{"default":{"summary":"estimate_maintenance request","value":{"propertyValue":100000,"ageYears":12,"units":1}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"estimatedAnnualMaintenance":{"type":"number"},"monthlyReserve":{"type":"number"},"maintenancePercentage":{"type":"number"},"currency":{"type":"string","const":"OMR"},"assumptionsUsed":{"type":"object","properties":{"ageYears":{"type":"number"},"units":{"type":"number"},"annualRatePct":{"type":"number"},"additionalUnitCost":{"type":"number"}},"required":["ageYears","units","annualRatePct","additionalUnitCost"],"additionalProperties":false},"methodology":{"type":"string"}},"required":["estimatedAnnualMaintenance","monthlyReserve","maintenancePercentage","currency","assumptionsUsed","methodology"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"estimate_maintenance response","value":{"success":true,"data":{"estimatedAnnualMaintenance":1300,"monthlyReserve":108.33,"maintenancePercentage":1.3,"currency":"OMR","assumptionsUsed":{"ageYears":12,"units":1,"annualRatePct":1.3,"additionalUnitCost":35},"methodology":"Annual reserve = propertyValue * annualRatePct / 100 + (units - 1) * additionalUnitCost. Uncalibrated heuristic; excludes property type and area."},"meta":{"requestId":"example-request","tool":"estimate_maintenance","price":0.02,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}},"deprecated":true}},"/api/v1/oman/property/analyze":{"post":{"operationId":"analyze_oman_property","tags":["Oman"],"summary":"Analyze an Oman residential property using local rental comparables, market context and investment metrics.","description":"Analyze an Oman residential property using local rental comparables, market context and investment metrics. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"governorate":{"type":"string","minLength":1,"maxLength":60},"wilayat":{"type":"string","minLength":1,"maxLength":60},"area":{"type":"string","minLength":1,"maxLength":80},"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":"integer","minimum":0,"maximum":20},"bathrooms":{"type":"integer","minimum":0,"maximum":20},"sizeSqm":{"type":"number","minimum":10,"maximum":5000},"askingPriceOMR":{"type":"number","minimum":1000,"maximum":1000000000},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished"]},"optionalAnnualServiceChargeOMR":{"type":"number","minimum":0,"maximum":1000000000},"optionalAnnualMaintenanceOMR":{"type":"number","minimum":0,"maximum":1000000000}},"required":["governorate","area","propertyType","sizeSqm","askingPriceOMR"],"additionalProperties":false},"examples":{"default":{"summary":"analyze_oman_property request","value":{"governorate":"Muscat","area":"Al Mouj","propertyType":"apartment","bedrooms":2,"sizeSqm":130,"askingPriceOMR":118000}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"normalizedLocation":{"type":"object","properties":{"governorate":{"type":"string"},"wilayat":{"type":"string"},"area":{"type":"string"},"inputArea":{"type":"string"},"matchType":{"type":"string","enum":["exact","alias","unmatched"]},"supported":{"type":"boolean"}},"required":["governorate","wilayat","area","inputArea","matchType","supported"],"additionalProperties":false},"subjectProperty":{"type":"object","properties":{"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"sizeSqm":{"type":"number"},"askingPriceOMR":{"type":"number"},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished","unspecified"]}},"required":["propertyType","bedrooms","bathrooms","sizeSqm","askingPriceOMR","furnished"],"additionalProperties":false},"market":{"type":"object","properties":{"estimatedMonthlyRentOMR":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"estimatedAnnualRentOMR":{"type":["number","null"]},"comparableCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sampleSizeUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimatedMonthlyRentOMR","estimatedAnnualRentOMR","comparableCount","sampleSizeUsed","dataFreshnessDays"],"additionalProperties":false},"investment":{"type":"object","properties":{"grossYieldPct":{"type":["number","null"]},"estimatedOperatingCostOMR":{"type":"number"},"estimatedNetIncomeOMR":{"type":["number","null"]},"netYieldPct":{"type":["number","null"]}},"required":["grossYieldPct","estimatedOperatingCostOMR","estimatedNetIncomeOMR","netYieldPct"],"additionalProperties":false},"pricePosition":{"type":"object","properties":{"askingPricePerSqmOMR":{"type":"number"},"observedComparableRange":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"marketPosition":{"type":"string","enum":["below_market","at_market","above_market","insufficient_data"]}},"required":["askingPricePerSqmOMR","observedComparableRange","marketPosition"],"additionalProperties":false},"comparablesSummary":{"anyOf":[{"type":"object","properties":{"medianRentPerSqm":{"type":"number"},"lowRentPerSqm":{"type":"number"},"highRentPerSqm":{"type":"number"}},"required":["medianRentPerSqm","lowRentPerSqm","highRentPerSqm"],"additionalProperties":false},{"type":"null"}]},"riskFlags":{"type":"array","items":{"type":"string"}},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1},"level":{"type":"string","enum":["insufficient","low","medium","high"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["score","level","reasons"],"additionalProperties":false},"provenance":{"type":"array","items":{"type":"object","properties":{"sourceType":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]},"sourceName":{"type":"string"},"sourceDate":{"type":"string"},"recordCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceType","sourceName","sourceDate","recordCount"],"additionalProperties":false}},"assumptions":{"type":"array","items":{"type":"string"}},"insufficientMarketData":{"type":"boolean"},"unavailableOutputs":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","const":"OMR"},"dataQuality":{"type":"object","properties":{"latestDataDate":{"type":["string","null"]},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sampleSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceTypes":{"type":"array","items":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]}},"staleMarketData":{"type":"boolean"}},"required":["latestDataDate","dataFreshnessDays","sampleSize","sourceTypes","staleMarketData"],"additionalProperties":false}},"required":["normalizedLocation","subjectProperty","market","investment","pricePosition","comparablesSummary","riskFlags","confidence","provenance","assumptions","insufficientMarketData","unavailableOutputs","currency","dataQuality"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"analyze_oman_property response","value":{"success":true,"data":{"normalizedLocation":{"governorate":"Muscat","wilayat":"Muscat","area":"Al Mouj","inputArea":"Al Mouj","matchType":"exact","supported":true},"subjectProperty":{"propertyType":"apartment","bedrooms":2,"bathrooms":null,"sizeSqm":130,"askingPriceOMR":118000,"furnished":"unspecified"},"market":{"estimatedMonthlyRentOMR":{"low":696.43,"median":731.25,"high":731.85},"estimatedAnnualRentOMR":8775,"comparableCount":4,"sampleSizeUsed":3,"dataFreshnessDays":185},"investment":{"grossYieldPct":7.44,"estimatedOperatingCostOMR":0,"estimatedNetIncomeOMR":8775,"netYieldPct":7.44},"pricePosition":{"askingPricePerSqmOMR":907.69,"observedComparableRange":null,"marketPosition":"insufficient_data"},"comparablesSummary":{"medianRentPerSqm":5.63,"lowRentPerSqm":5.36,"highRentPerSqm":5.63},"riskFlags":["outliers_removed","insufficient_sale_market_data","demo_dataset_not_live_market_data"],"confidence":{"score":0.73,"level":"high","reasons":["Sample size of 3 comparable(s) used (target is 8+ for full confidence on this factor).","Comparable data has a median age of 185 day(s) (data older than 540 days is excluded before this point).","Comparable size deviates 4% from the subject on average; 100% of comparables match the bedroom count exactly.","Price dispersion across comparables (coefficient of variation) is 0.02.","1 statistical outlier(s) were removed from the comparable pool before scoring."]},"provenance":[{"sourceType":"manual_benchmark","sourceName":"Rafid curated Muscat benchmark dataset (demo/MVP — illustrative figures, not sourced from live listings or completed transactions)","sourceDate":"2026-06-01","recordCount":5}],"assumptions":["No annual service charge supplied; treated as 0 OMR in operating cost.","No annual maintenance cost supplied; treated as 0 OMR in operating cost.","1 statistical outlier(s) were removed from the rental comparable sample.","Some or all comparable figures come from a curated demo/MVP benchmark dataset (see provenance); they are illustrative, not sourced from live listings or completed transactions."],"insufficientMarketData":false,"unavailableOutputs":["pricePosition.observedComparableRange","pricePosition.marketPosition"],"currency":"OMR","dataQuality":{"latestDataDate":"2026-05-25","dataFreshnessDays":185,"sampleSize":3,"sourceTypes":["manual_benchmark"],"staleMarketData":false}},"meta":{"requestId":"example-request","tool":"analyze_oman_property","price":0.25,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/v1/oman/property/analyze":{"post":{"operationId":"analyze_oman_property_legacy","tags":["Oman"],"summary":"Analyze an Oman residential property using local rental comparables, market context and investment metrics.","description":"Analyze an Oman residential property using local rental comparables, market context and investment metrics. Click Authorize and enter an active Rafid API key before using Try it out.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"governorate":{"type":"string","minLength":1,"maxLength":60},"wilayat":{"type":"string","minLength":1,"maxLength":60},"area":{"type":"string","minLength":1,"maxLength":80},"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":"integer","minimum":0,"maximum":20},"bathrooms":{"type":"integer","minimum":0,"maximum":20},"sizeSqm":{"type":"number","minimum":10,"maximum":5000},"askingPriceOMR":{"type":"number","minimum":1000,"maximum":1000000000},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished"]},"optionalAnnualServiceChargeOMR":{"type":"number","minimum":0,"maximum":1000000000},"optionalAnnualMaintenanceOMR":{"type":"number","minimum":0,"maximum":1000000000}},"required":["governorate","area","propertyType","sizeSqm","askingPriceOMR"],"additionalProperties":false},"examples":{"default":{"summary":"analyze_oman_property request","value":{"governorate":"Muscat","area":"Al Mouj","propertyType":"apartment","bedrooms":2,"sizeSqm":130,"askingPriceOMR":118000}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"normalizedLocation":{"type":"object","properties":{"governorate":{"type":"string"},"wilayat":{"type":"string"},"area":{"type":"string"},"inputArea":{"type":"string"},"matchType":{"type":"string","enum":["exact","alias","unmatched"]},"supported":{"type":"boolean"}},"required":["governorate","wilayat","area","inputArea","matchType","supported"],"additionalProperties":false},"subjectProperty":{"type":"object","properties":{"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"sizeSqm":{"type":"number"},"askingPriceOMR":{"type":"number"},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished","unspecified"]}},"required":["propertyType","bedrooms","bathrooms","sizeSqm","askingPriceOMR","furnished"],"additionalProperties":false},"market":{"type":"object","properties":{"estimatedMonthlyRentOMR":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"estimatedAnnualRentOMR":{"type":["number","null"]},"comparableCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sampleSizeUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimatedMonthlyRentOMR","estimatedAnnualRentOMR","comparableCount","sampleSizeUsed","dataFreshnessDays"],"additionalProperties":false},"investment":{"type":"object","properties":{"grossYieldPct":{"type":["number","null"]},"estimatedOperatingCostOMR":{"type":"number"},"estimatedNetIncomeOMR":{"type":["number","null"]},"netYieldPct":{"type":["number","null"]}},"required":["grossYieldPct","estimatedOperatingCostOMR","estimatedNetIncomeOMR","netYieldPct"],"additionalProperties":false},"pricePosition":{"type":"object","properties":{"askingPricePerSqmOMR":{"type":"number"},"observedComparableRange":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"marketPosition":{"type":"string","enum":["below_market","at_market","above_market","insufficient_data"]}},"required":["askingPricePerSqmOMR","observedComparableRange","marketPosition"],"additionalProperties":false},"comparablesSummary":{"anyOf":[{"type":"object","properties":{"medianRentPerSqm":{"type":"number"},"lowRentPerSqm":{"type":"number"},"highRentPerSqm":{"type":"number"}},"required":["medianRentPerSqm","lowRentPerSqm","highRentPerSqm"],"additionalProperties":false},{"type":"null"}]},"riskFlags":{"type":"array","items":{"type":"string"}},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1},"level":{"type":"string","enum":["insufficient","low","medium","high"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["score","level","reasons"],"additionalProperties":false},"provenance":{"type":"array","items":{"type":"object","properties":{"sourceType":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]},"sourceName":{"type":"string"},"sourceDate":{"type":"string"},"recordCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceType","sourceName","sourceDate","recordCount"],"additionalProperties":false}},"assumptions":{"type":"array","items":{"type":"string"}},"insufficientMarketData":{"type":"boolean"},"unavailableOutputs":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","const":"OMR"},"dataQuality":{"type":"object","properties":{"latestDataDate":{"type":["string","null"]},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sampleSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceTypes":{"type":"array","items":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]}},"staleMarketData":{"type":"boolean"}},"required":["latestDataDate","dataFreshnessDays","sampleSize","sourceTypes","staleMarketData"],"additionalProperties":false}},"required":["normalizedLocation","subjectProperty","market","investment","pricePosition","comparablesSummary","riskFlags","confidence","provenance","assumptions","insufficientMarketData","unavailableOutputs","currency","dataQuality"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"analyze_oman_property response","value":{"success":true,"data":{"normalizedLocation":{"governorate":"Muscat","wilayat":"Muscat","area":"Al Mouj","inputArea":"Al Mouj","matchType":"exact","supported":true},"subjectProperty":{"propertyType":"apartment","bedrooms":2,"bathrooms":null,"sizeSqm":130,"askingPriceOMR":118000,"furnished":"unspecified"},"market":{"estimatedMonthlyRentOMR":{"low":696.43,"median":731.25,"high":731.85},"estimatedAnnualRentOMR":8775,"comparableCount":4,"sampleSizeUsed":3,"dataFreshnessDays":185},"investment":{"grossYieldPct":7.44,"estimatedOperatingCostOMR":0,"estimatedNetIncomeOMR":8775,"netYieldPct":7.44},"pricePosition":{"askingPricePerSqmOMR":907.69,"observedComparableRange":null,"marketPosition":"insufficient_data"},"comparablesSummary":{"medianRentPerSqm":5.63,"lowRentPerSqm":5.36,"highRentPerSqm":5.63},"riskFlags":["outliers_removed","insufficient_sale_market_data","demo_dataset_not_live_market_data"],"confidence":{"score":0.73,"level":"high","reasons":["Sample size of 3 comparable(s) used (target is 8+ for full confidence on this factor).","Comparable data has a median age of 185 day(s) (data older than 540 days is excluded before this point).","Comparable size deviates 4% from the subject on average; 100% of comparables match the bedroom count exactly.","Price dispersion across comparables (coefficient of variation) is 0.02.","1 statistical outlier(s) were removed from the comparable pool before scoring."]},"provenance":[{"sourceType":"manual_benchmark","sourceName":"Rafid curated Muscat benchmark dataset (demo/MVP — illustrative figures, not sourced from live listings or completed transactions)","sourceDate":"2026-06-01","recordCount":5}],"assumptions":["No annual service charge supplied; treated as 0 OMR in operating cost.","No annual maintenance cost supplied; treated as 0 OMR in operating cost.","1 statistical outlier(s) were removed from the rental comparable sample.","Some or all comparable figures come from a curated demo/MVP benchmark dataset (see provenance); they are illustrative, not sourced from live listings or completed transactions."],"insufficientMarketData":false,"unavailableOutputs":["pricePosition.observedComparableRange","pricePosition.marketPosition"],"currency":"OMR","dataQuality":{"latestDataDate":"2026-05-25","dataFreshnessDays":185,"sampleSize":3,"sourceTypes":["manual_benchmark"],"staleMarketData":false}},"meta":{"requestId":"example-request","tool":"analyze_oman_property","price":0.25,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"401":{"description":"A valid X-API-Key header is required","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"A valid X-API-Key header is required"},"meta":{"requestId":"example-request"}}}}}}},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}},"deprecated":true}},"/api/v1/x402/property/analyze":{"post":{"operationId":"analyze_property_x402","tags":["x402"],"summary":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only. (pay-per-call via x402, no API key)","description":"Requires a valid X-PAYMENT header per the x402 protocol instead of X-API-Key. Send the request without an X-PAYMENT header first to receive a 402 response listing accepted payment options (price, network and receiving address).","security":[],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000}},"required":["propertyValue","annualRent"],"additionalProperties":false},"examples":{"default":{"summary":"analyze_property request","value":{"propertyValue":85000,"annualRent":7200,"serviceCharge":650,"maintenanceCost":400}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"analyze_property response","value":{"success":true,"data":{"propertyValue":85000,"annualRent":7200,"grossAnnualIncome":7200,"grossYield":8.47,"netYield":7.24,"annualOperatingCost":1050,"annualNetIncome":6150,"effectiveAnnualRent":7200,"paybackYears":13.82,"grossYieldPct":8.47,"netYieldPct":7.24,"annualOperatingCosts":1050,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."},"meta":{"requestId":"example-request","tool":"analyze_property","price":0.01,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"402":{"description":"Payment required — 0.01 USD in USDC on eip155:8453. Response body lists accepted payment options per the x402 protocol."},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/x402/property/compare":{"post":{"operationId":"compare_properties_x402","tags":["x402"],"summary":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties. (pay-per-call via x402, no API key)","description":"Requires a valid X-PAYMENT header per the x402 protocol instead of X-API-Key. Send the request without an X-PAYMENT header first to receive a 402 response listing accepted payment options (price, network and receiving address).","security":[],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["propertyValue","annualRent","name"],"additionalProperties":false}}},"required":["properties"],"additionalProperties":false},"examples":{"default":{"summary":"compare_properties request","value":{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200},{"name":"B","propertyValue":100000,"annualRent":7000}]}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"},"name":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note","name"],"additionalProperties":false}},"sortedByNetYield":{"type":"array","items":{"type":"string"}}},"required":["properties","sortedByNetYield"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"compare_properties response","value":{"success":true,"data":{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200,"grossAnnualIncome":7200,"grossYield":8.47,"netYield":8.47,"annualOperatingCost":0,"annualNetIncome":7200,"effectiveAnnualRent":7200,"paybackYears":11.81,"grossYieldPct":8.47,"netYieldPct":8.47,"annualOperatingCosts":0,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."},{"name":"B","propertyValue":100000,"annualRent":7000,"grossAnnualIncome":7000,"grossYield":7,"netYield":7,"annualOperatingCost":0,"annualNetIncome":7000,"effectiveAnnualRent":7000,"paybackYears":14.29,"grossYieldPct":7,"netYieldPct":7,"annualOperatingCosts":0,"currency":"OMR","note":"Calculations only; excludes financing, taxes, transaction fees and capital appreciation."}],"sortedByNetYield":["A","B"]},"meta":{"requestId":"example-request","tool":"compare_properties","price":0.03,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"402":{"description":"Payment required — 0.03 USD in USDC on eip155:8453. Response body lists accepted payment options per the x402 protocol."},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/x402/maintenance/estimate":{"post":{"operationId":"estimate_maintenance_x402","tags":["x402"],"summary":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey. (pay-per-call via x402, no API key)","description":"Requires a valid X-PAYMENT header per the x402 protocol instead of X-API-Key. Send the request without an X-PAYMENT header first to receive a 402 response listing accepted payment options (price, network and receiving address).","security":[],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"ageYears":{"type":"number","minimum":0,"maximum":200},"units":{"type":"integer","minimum":1,"maximum":10000},"annualRent":{"description":"Legacy input; unused in this value-based estimate","type":"number","minimum":0,"maximum":1000000000000},"assumptions":{"type":"object","properties":{"annualRatePct":{"type":"number","minimum":0,"maximum":100},"additionalUnitCost":{"type":"number","minimum":0,"maximum":1000000000000}},"additionalProperties":false}},"required":["propertyValue"],"additionalProperties":false},"examples":{"default":{"summary":"estimate_maintenance request","value":{"propertyValue":100000,"ageYears":12,"units":1}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"estimatedAnnualMaintenance":{"type":"number"},"monthlyReserve":{"type":"number"},"maintenancePercentage":{"type":"number"},"currency":{"type":"string","const":"OMR"},"assumptionsUsed":{"type":"object","properties":{"ageYears":{"type":"number"},"units":{"type":"number"},"annualRatePct":{"type":"number"},"additionalUnitCost":{"type":"number"}},"required":["ageYears","units","annualRatePct","additionalUnitCost"],"additionalProperties":false},"methodology":{"type":"string"}},"required":["estimatedAnnualMaintenance","monthlyReserve","maintenancePercentage","currency","assumptionsUsed","methodology"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"estimate_maintenance response","value":{"success":true,"data":{"estimatedAnnualMaintenance":1300,"monthlyReserve":108.33,"maintenancePercentage":1.3,"currency":"OMR","assumptionsUsed":{"ageYears":12,"units":1,"annualRatePct":1.3,"additionalUnitCost":35},"methodology":"Annual reserve = propertyValue * annualRatePct / 100 + (units - 1) * additionalUnitCost. Uncalibrated heuristic; excludes property type and area."},"meta":{"requestId":"example-request","tool":"estimate_maintenance","price":0.02,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"402":{"description":"Payment required — 0.02 USD in USDC on eip155:8453. Response body lists accepted payment options per the x402 protocol."},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/x402/oman/property/analyze":{"post":{"operationId":"analyze_oman_property_x402","tags":["x402"],"summary":"Analyze an Oman residential property using local rental comparables, market context and investment metrics. (pay-per-call via x402, no API key)","description":"Requires a valid X-PAYMENT header per the x402 protocol instead of X-API-Key. Send the request without an X-PAYMENT header first to receive a 402 response listing accepted payment options (price, network and receiving address).","security":[],"requestBody":{"required":true,"description":"Strict JSON input; unknown fields are rejected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"governorate":{"type":"string","minLength":1,"maxLength":60},"wilayat":{"type":"string","minLength":1,"maxLength":60},"area":{"type":"string","minLength":1,"maxLength":80},"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":"integer","minimum":0,"maximum":20},"bathrooms":{"type":"integer","minimum":0,"maximum":20},"sizeSqm":{"type":"number","minimum":10,"maximum":5000},"askingPriceOMR":{"type":"number","minimum":1000,"maximum":1000000000},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished"]},"optionalAnnualServiceChargeOMR":{"type":"number","minimum":0,"maximum":1000000000},"optionalAnnualMaintenanceOMR":{"type":"number","minimum":0,"maximum":1000000000}},"required":["governorate","area","propertyType","sizeSqm","askingPriceOMR"],"additionalProperties":false},"examples":{"default":{"summary":"analyze_oman_property request","value":{"governorate":"Muscat","area":"Al Mouj","propertyType":"apartment","bedrooms":2,"sizeSqm":130,"askingPriceOMR":118000}}}}}},"responses":{"200":{"description":"Calculated metrics","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"normalizedLocation":{"type":"object","properties":{"governorate":{"type":"string"},"wilayat":{"type":"string"},"area":{"type":"string"},"inputArea":{"type":"string"},"matchType":{"type":"string","enum":["exact","alias","unmatched"]},"supported":{"type":"boolean"}},"required":["governorate","wilayat","area","inputArea","matchType","supported"],"additionalProperties":false},"subjectProperty":{"type":"object","properties":{"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"sizeSqm":{"type":"number"},"askingPriceOMR":{"type":"number"},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished","unspecified"]}},"required":["propertyType","bedrooms","bathrooms","sizeSqm","askingPriceOMR","furnished"],"additionalProperties":false},"market":{"type":"object","properties":{"estimatedMonthlyRentOMR":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"estimatedAnnualRentOMR":{"type":["number","null"]},"comparableCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sampleSizeUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimatedMonthlyRentOMR","estimatedAnnualRentOMR","comparableCount","sampleSizeUsed","dataFreshnessDays"],"additionalProperties":false},"investment":{"type":"object","properties":{"grossYieldPct":{"type":["number","null"]},"estimatedOperatingCostOMR":{"type":"number"},"estimatedNetIncomeOMR":{"type":["number","null"]},"netYieldPct":{"type":["number","null"]}},"required":["grossYieldPct","estimatedOperatingCostOMR","estimatedNetIncomeOMR","netYieldPct"],"additionalProperties":false},"pricePosition":{"type":"object","properties":{"askingPricePerSqmOMR":{"type":"number"},"observedComparableRange":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"marketPosition":{"type":"string","enum":["below_market","at_market","above_market","insufficient_data"]}},"required":["askingPricePerSqmOMR","observedComparableRange","marketPosition"],"additionalProperties":false},"comparablesSummary":{"anyOf":[{"type":"object","properties":{"medianRentPerSqm":{"type":"number"},"lowRentPerSqm":{"type":"number"},"highRentPerSqm":{"type":"number"}},"required":["medianRentPerSqm","lowRentPerSqm","highRentPerSqm"],"additionalProperties":false},{"type":"null"}]},"riskFlags":{"type":"array","items":{"type":"string"}},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1},"level":{"type":"string","enum":["insufficient","low","medium","high"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["score","level","reasons"],"additionalProperties":false},"provenance":{"type":"array","items":{"type":"object","properties":{"sourceType":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]},"sourceName":{"type":"string"},"sourceDate":{"type":"string"},"recordCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceType","sourceName","sourceDate","recordCount"],"additionalProperties":false}},"assumptions":{"type":"array","items":{"type":"string"}},"insufficientMarketData":{"type":"boolean"},"unavailableOutputs":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","const":"OMR"},"dataQuality":{"type":"object","properties":{"latestDataDate":{"type":["string","null"]},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sampleSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceTypes":{"type":"array","items":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]}},"staleMarketData":{"type":"boolean"}},"required":["latestDataDate","dataFreshnessDays","sampleSize","sourceTypes","staleMarketData"],"additionalProperties":false}},"required":["normalizedLocation","subjectProperty","market","investment","pricePosition","comparablesSummary","riskFlags","confidence","provenance","assumptions","insufficientMarketData","unavailableOutputs","currency","dataQuality"],"additionalProperties":false},"meta":{"type":"object","required":["requestId","tool","price","currency"],"properties":{"requestId":{"type":"string"},"tool":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}}}}},"examples":{"default":{"summary":"analyze_oman_property response","value":{"success":true,"data":{"normalizedLocation":{"governorate":"Muscat","wilayat":"Muscat","area":"Al Mouj","inputArea":"Al Mouj","matchType":"exact","supported":true},"subjectProperty":{"propertyType":"apartment","bedrooms":2,"bathrooms":null,"sizeSqm":130,"askingPriceOMR":118000,"furnished":"unspecified"},"market":{"estimatedMonthlyRentOMR":{"low":696.43,"median":731.25,"high":731.85},"estimatedAnnualRentOMR":8775,"comparableCount":4,"sampleSizeUsed":3,"dataFreshnessDays":185},"investment":{"grossYieldPct":7.44,"estimatedOperatingCostOMR":0,"estimatedNetIncomeOMR":8775,"netYieldPct":7.44},"pricePosition":{"askingPricePerSqmOMR":907.69,"observedComparableRange":null,"marketPosition":"insufficient_data"},"comparablesSummary":{"medianRentPerSqm":5.63,"lowRentPerSqm":5.36,"highRentPerSqm":5.63},"riskFlags":["outliers_removed","insufficient_sale_market_data","demo_dataset_not_live_market_data"],"confidence":{"score":0.73,"level":"high","reasons":["Sample size of 3 comparable(s) used (target is 8+ for full confidence on this factor).","Comparable data has a median age of 185 day(s) (data older than 540 days is excluded before this point).","Comparable size deviates 4% from the subject on average; 100% of comparables match the bedroom count exactly.","Price dispersion across comparables (coefficient of variation) is 0.02.","1 statistical outlier(s) were removed from the comparable pool before scoring."]},"provenance":[{"sourceType":"manual_benchmark","sourceName":"Rafid curated Muscat benchmark dataset (demo/MVP — illustrative figures, not sourced from live listings or completed transactions)","sourceDate":"2026-06-01","recordCount":5}],"assumptions":["No annual service charge supplied; treated as 0 OMR in operating cost.","No annual maintenance cost supplied; treated as 0 OMR in operating cost.","1 statistical outlier(s) were removed from the rental comparable sample.","Some or all comparable figures come from a curated demo/MVP benchmark dataset (see provenance); they are illustrative, not sourced from live listings or completed transactions."],"insufficientMarketData":false,"unavailableOutputs":["pricePosition.observedComparableRange","pricePosition.marketPosition"],"currency":"OMR","dataQuality":{"latestDataDate":"2026-05-25","dataFreshnessDays":185,"sampleSize":3,"sourceTypes":["manual_benchmark"],"staleMarketData":false}},"meta":{"requestId":"example-request","tool":"analyze_oman_property","price":0.25,"currency":"USD"}}}}}}},"400":{"description":"Input validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INVALID_INPUT","message":"Input validation failed"},"meta":{"requestId":"example-request"}}}}}}},"402":{"description":"Payment required — 0.25 USD in USDC on eip155:8453. Response body lists accepted payment options per the x402 protocol."},"413":{"description":"Request body exceeds 32kb","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds 32kb"},"meta":{"requestId":"example-request"}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Use application/json"},"meta":{"requestId":"example-request"}}}}}}},"429":{"description":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"RATE_LIMITED","message":"Per-minute limit or monthly quota exceeded (QUOTA_EXCEEDED)"},"meta":{"requestId":"example-request"}}}}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"requestId":"example-request"}}}}}}},"503":{"description":"Customer or usage storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["success","error","meta"],"properties":{"success":{"const":false},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"examples":{"default":{"summary":"Example","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Customer or usage storage unavailable"},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/health":{"get":{"operationId":"health","tags":["System"],"summary":"Process liveness","description":"Public liveness endpoint. No API key is required.","security":[],"responses":{"200":{"description":"Alive","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"ok":true},"meta":{"requestId":"example-request"}}}}}}}}}},"/health":{"get":{"operationId":"health_legacy","tags":["System"],"summary":"Process liveness","description":"Public liveness endpoint. No API key is required.","security":[],"responses":{"200":{"description":"Alive","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"ok":true},"meta":{"requestId":"example-request"}}}}}}}}}},"/":{"get":{"operationId":"discovery","tags":["System"],"summary":"Service metadata or a browser-facing landing page","description":"Returns an HTML landing page for browsers (Accept: text/html, the default) and a JSON discovery payload for machine/agent clients that send Accept: application/json.","security":[],"responses":{"200":{"description":"Discovery (JSON) or landing page (HTML)","content":{"application/json":{"schema":{"type":"object","required":["name","version","docs","openapi","health","endpoints"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"docs":{"type":"string"},"openapi":{"type":"string"},"health":{"type":"string"},"agent":{"type":"string"},"pricing":{"type":"string"},"tools":{"type":"string"},"x402":{"type":"string"},"endpoints":{"type":"array","items":{"type":"string"}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"name":"Rafid Agent API","version":"0.1.0","docs":"/docs","openapi":"/openapi.json","health":"/api/v1/health","agent":"/api/v1/agent","pricing":"/api/v1/pricing","tools":"/api/v1/tools","x402":"/api/v1/x402","endpoints":["/api/v1/property/analyze","/api/v1/property/compare","/api/v1/maintenance/estimate","/api/v1/oman/property/analyze"]},"meta":{"requestId":"example-request"}}}}},"text/html":{"schema":{"type":"string"}}}}}}},"/docs":{"get":{"operationId":"swagger_docs","tags":["System"],"summary":"Interactive Swagger UI","description":"Browser interface for exploring the API, authorizing with X-API-Key, and sending test requests.","security":[],"responses":{"200":{"description":"Swagger UI HTML","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","tags":["System"],"summary":"Raw OpenAPI discovery document (no envelope)","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object","required":["openapi","info","paths"],"properties":{"openapi":{"type":"string"},"info":{"type":"object"},"paths":{"type":"object"}}}}}}}}},"/api/v1/agent":{"get":{"operationId":"agent","tags":["Agent"],"summary":"Agent-marketplace metadata","description":"Machine-readable service metadata for AI agents and agent directories/marketplaces.","security":[],"responses":{"200":{"description":"Agent metadata","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["name","description","version","mcp","openapi","pricing","x402"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"mcp":{"type":"boolean"},"docs":{"type":"string"},"openapi":{"type":"string"},"health":{"type":"string"},"pricing":{"type":"string"},"tools":{"type":"string"},"x402":{"type":"string"},"x402Enabled":{"type":"boolean"},"endpoints":{"type":"array","items":{"type":"string"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"name":"Rafid Property Intelligence","description":"Property and facility intelligence tools built for autonomous AI agents: discover a capability, pay per call over x402 (or authenticate with an API key), execute, get a structured result.","version":"0.1.0","audience":"ai-agents","protocols":[{"protocol":"mcp","role":"primary","description":"Local stdio MCP server exposing every capability as a tool with strict input/output schemas.","transport":"stdio","remote":false},{"protocol":"x402","role":"primary","enabled":true,"description":"Pay-per-call, no account or API key: discover price via GET /api/v1/x402, pay, call.","network":"eip155:8453"},{"protocol":"rest","role":"compatibility","description":"X-API-Key authenticated REST routes. Underlying transport shared by MCP and the informational endpoints below; not the primary integration path for agents."}],"mcp":true,"docs":"/docs","openapi":"/openapi.json","health":"/api/v1/health","manifest":"/agent.json","wellKnown":["/.well-known/ai-plugin.json","/.well-known/agent.json"],"llmsTxt":"/llms.txt","pricing":"/api/v1/pricing","tools":"/api/v1/tools","capabilities":"/api/v1/capabilities","x402":"/api/v1/x402","x402Enabled":true,"endpoints":["/api/v1/property/analyze","/api/v1/property/compare","/api/v1/maintenance/estimate","/api/v1/oman/property/analyze"],"roadmap":[{"name":"estimate_property_rent","description":"Estimate achievable market rent for a property from comparable listings.","status":"planned"},{"name":"analyze_lease","description":"Extract and evaluate key terms, obligations and risk flags from a lease document.","status":"planned"},{"name":"check_contract_risk","description":"Flag risky or unusual clauses in a property-related contract.","status":"planned"},{"name":"diagnose_maintenance_issue","description":"Triage a described maintenance issue toward likely cause and urgency.","status":"planned"},{"name":"estimate_repair_cost","description":"Estimate the cost of a specific repair, as a calibrated alternative to the general maintenance reserve heuristic.","status":"planned"},{"name":"generate_property_report","description":"Compose a structured report document from one or more other tool results.","status":"planned"}]},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/pricing":{"get":{"operationId":"pricing","tags":["Agent"],"summary":"Pay-per-call pricing","description":"Structured, centralized pricing for every tool. Sourced from a single price catalog shared with the x402 payment gate — never duplicated.","security":[],"responses":{"200":{"description":"Pricing","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["currency","model","tools"],"properties":{"currency":{"type":"string"},"model":{"type":"string"},"tools":{"type":"object","additionalProperties":{"type":"number"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"currency":"USD","model":"pay-per-call","tools":{"analyze_property":0.01,"compare_properties":0.03,"estimate_maintenance":0.02,"analyze_oman_property":0.25}},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/tools":{"get":{"operationId":"tools","tags":["Agent"],"summary":"Tool catalog for AI agents","description":"Every tool available to AI agents: name, description, price, endpoint, method, input JSON Schema and a derived output summary.","security":[],"responses":{"200":{"description":"Tool catalog","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"type":"object","required":["name","description","price","currency","endpoint","method","inputSchema","outputSummary"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"endpoint":{"type":"string"},"x402Endpoint":{"type":"string"},"method":{"type":"string"},"inputSchema":{"type":"object"},"outputSummary":{"type":"string"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":[{"name":"analyze_property","description":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.","price":0.01,"currency":"USD","endpoint":"/api/v1/property/analyze","x402Endpoint":"/api/v1/x402/property/analyze","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000}},"required":["propertyValue","annualRent"],"additionalProperties":false},"outputSummary":"Returns propertyValue, annualRent, grossAnnualIncome, grossYield, netYield, annualOperatingCost, annualNetIncome, effectiveAnnualRent, paybackYears, grossYieldPct, netYieldPct, annualOperatingCosts, currency, note."},{"name":"compare_properties","description":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.","price":0.03,"currency":"USD","endpoint":"/api/v1/property/compare","x402Endpoint":"/api/v1/x402/property/compare","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["propertyValue","annualRent","name"],"additionalProperties":false}}},"required":["properties"],"additionalProperties":false},"outputSummary":"Returns properties, sortedByNetYield."},{"name":"estimate_maintenance","description":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.","price":0.02,"currency":"USD","endpoint":"/api/v1/maintenance/estimate","x402Endpoint":"/api/v1/x402/maintenance/estimate","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"ageYears":{"type":"number","minimum":0,"maximum":200},"units":{"type":"integer","minimum":1,"maximum":10000},"annualRent":{"description":"Legacy input; unused in this value-based estimate","type":"number","minimum":0,"maximum":1000000000000},"assumptions":{"type":"object","properties":{"annualRatePct":{"type":"number","minimum":0,"maximum":100},"additionalUnitCost":{"type":"number","minimum":0,"maximum":1000000000000}},"additionalProperties":false}},"required":["propertyValue"],"additionalProperties":false},"outputSummary":"Returns estimatedAnnualMaintenance, monthlyReserve, maintenancePercentage, currency, assumptionsUsed, methodology."},{"name":"analyze_oman_property","description":"Analyze an Oman residential property using local rental comparables, market context and investment metrics.","price":0.25,"currency":"USD","endpoint":"/api/v1/oman/property/analyze","x402Endpoint":"/api/v1/x402/oman/property/analyze","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"governorate":{"type":"string","minLength":1,"maxLength":60},"wilayat":{"type":"string","minLength":1,"maxLength":60},"area":{"type":"string","minLength":1,"maxLength":80},"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":"integer","minimum":0,"maximum":20},"bathrooms":{"type":"integer","minimum":0,"maximum":20},"sizeSqm":{"type":"number","minimum":10,"maximum":5000},"askingPriceOMR":{"type":"number","minimum":1000,"maximum":1000000000},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished"]},"optionalAnnualServiceChargeOMR":{"type":"number","minimum":0,"maximum":1000000000},"optionalAnnualMaintenanceOMR":{"type":"number","minimum":0,"maximum":1000000000}},"required":["governorate","area","propertyType","sizeSqm","askingPriceOMR"],"additionalProperties":false},"outputSummary":"Returns normalizedLocation, subjectProperty, market, investment, pricePosition, comparablesSummary, riskFlags, confidence, provenance, assumptions, insufficientMarketData, unavailableOutputs, currency, dataQuality."}],"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/x402":{"get":{"operationId":"x402_info","tags":["x402"],"summary":"x402 protocol and pricing information","description":"Always available, independent of X402_ENABLED, so an agent can discover pricing/network support before deciding whether to pay. No wallet secret is ever included.","security":[],"responses":{"200":{"description":"x402 protocol info","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["protocol","x402Version","scheme","enabled","tools"],"properties":{"protocol":{"type":"string"},"x402Version":{"type":"integer"},"scheme":{"type":"string"},"enabled":{"type":"boolean"},"network":{"type":["string","null"]},"payTo":{"type":["string","null"]},"facilitator":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","required":["name","endpoint","price"],"properties":{"name":{"type":"string"},"endpoint":{"type":"string"},"price":{"type":"number"}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"protocol":"x402","x402Version":2,"scheme":"exact","enabled":true,"network":"eip155:8453","payTo":null,"facilitator":null,"tools":[{"name":"analyze_property","endpoint":"/api/v1/x402/property/analyze","price":0.01},{"name":"compare_properties","endpoint":"/api/v1/x402/property/compare","price":0.03},{"name":"estimate_maintenance","endpoint":"/api/v1/x402/maintenance/estimate","price":0.02},{"name":"analyze_oman_property","endpoint":"/api/v1/x402/oman/property/analyze","price":0.25}]},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/x402/status":{"get":{"operationId":"x402_status","tags":["x402"],"summary":"Factual x402 runtime status","description":"A small, always-on status report so a caller never has to infer payment enforcement from marketing copy: every field is read directly from validated configuration. Never includes a wallet private key or any other secret.","security":[],"responses":{"200":{"description":"x402 runtime status","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["enabled","mode","network","asset","facilitator","walletConfigured","paymentEnforcement"],"properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["disabled","testnet","production"]},"network":{"type":["string","null"]},"asset":{"type":["string","null"]},"facilitator":{"type":["string","null"]},"walletConfigured":{"type":"boolean"},"paymentEnforcement":{"type":"boolean"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"enabled":true,"mode":"production","network":"eip155:8453","asset":"USDC","facilitator":"coinbase-cdp","walletConfigured":true,"paymentEnforcement":true},"meta":{"requestId":"example-request"}}}}}}}}}},"/api/v1/capabilities":{"get":{"operationId":"capabilities","tags":["Agent"],"summary":"Machine-first capability registry","description":"The full capability registry — schemas, pricing, when to use, examples — optimized for an agent (or the model behind it) to decide what to call without reading prose. The single source every other discovery endpoint here reuses.","security":[],"responses":{"200":{"description":"Capability registry","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"type":"object","required":["name","description","whenToUse","price","currency","paymentProtocol","endpoint","inputSchema","outputSchema"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"whenToUse":{"type":"string"},"useCases":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"currency":{"type":"string"},"paymentProtocol":{"type":"string"},"network":{"type":["string","null"]},"idempotent":{"type":"boolean"},"sideEffects":{"type":"boolean"},"endpoint":{"type":"string"},"x402Endpoint":{"type":"string"},"method":{"type":"string"},"inputSchema":{"type":"object"},"outputSchema":{"type":"object"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":[{"name":"analyze_property","description":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.","whenToUse":"Use when an agent needs financial metrics (yield, income, payback) for a single property.","useCases":["property investment analysis","rental yield check","single-property evaluation","buy vs. hold financial screening"],"price":0.01,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/property/analyze","x402Endpoint":"/api/v1/x402/property/analyze","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000}},"required":["propertyValue","annualRent"],"additionalProperties":false,"examples":[{"propertyValue":85000,"annualRent":7200,"serviceCharge":650,"maintenanceCost":400}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note"],"additionalProperties":false}},{"name":"compare_properties","description":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.","whenToUse":"Use when an agent must rank or choose between 2-20 candidate properties by net yield.","useCases":["property comparison","ranking multiple properties","portfolio shortlisting","choosing between investment options"],"price":0.03,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/property/compare","x402Endpoint":"/api/v1/x402/property/compare","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["propertyValue","annualRent","name"],"additionalProperties":false}}},"required":["properties"],"additionalProperties":false,"examples":[{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200},{"name":"B","propertyValue":100000,"annualRent":7000}]}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"},"name":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note","name"],"additionalProperties":false}},"sortedByNetYield":{"type":"array","items":{"type":"string"}}},"required":["properties","sortedByNetYield"],"additionalProperties":false}},{"name":"estimate_maintenance","description":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.","whenToUse":"Use when an agent needs an annual maintenance reserve estimate for a property, not an actual inspection.","useCases":["maintenance budgeting","annual reserve estimation","facility cost planning","pre-purchase cost forecasting"],"price":0.02,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/maintenance/estimate","x402Endpoint":"/api/v1/x402/maintenance/estimate","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"ageYears":{"type":"number","minimum":0,"maximum":200},"units":{"type":"integer","minimum":1,"maximum":10000},"annualRent":{"description":"Legacy input; unused in this value-based estimate","type":"number","minimum":0,"maximum":1000000000000},"assumptions":{"type":"object","properties":{"annualRatePct":{"type":"number","minimum":0,"maximum":100},"additionalUnitCost":{"type":"number","minimum":0,"maximum":1000000000000}},"additionalProperties":false}},"required":["propertyValue"],"additionalProperties":false,"examples":[{"propertyValue":100000,"ageYears":12,"units":1}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"estimatedAnnualMaintenance":{"type":"number"},"monthlyReserve":{"type":"number"},"maintenancePercentage":{"type":"number"},"currency":{"type":"string","const":"OMR"},"assumptionsUsed":{"type":"object","properties":{"ageYears":{"type":"number"},"units":{"type":"number"},"annualRatePct":{"type":"number"},"additionalUnitCost":{"type":"number"}},"required":["ageYears","units","annualRatePct","additionalUnitCost"],"additionalProperties":false},"methodology":{"type":"string"}},"required":["estimatedAnnualMaintenance","monthlyReserve","maintenancePercentage","currency","assumptionsUsed","methodology"],"additionalProperties":false}},{"name":"analyze_oman_property","description":"Analyze an Oman residential property using local rental comparables, market context and investment metrics.","whenToUse":"Use when an agent needs Oman-specific rental, yield, price-position or operating-cost analysis.","useCases":["Oman rental investment analysis","Muscat property market comparison","rental yield with local comparables","Oman price-per-sqm benchmarking"],"price":0.25,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/oman/property/analyze","x402Endpoint":"/api/v1/x402/oman/property/analyze","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"governorate":{"type":"string","minLength":1,"maxLength":60},"wilayat":{"type":"string","minLength":1,"maxLength":60},"area":{"type":"string","minLength":1,"maxLength":80},"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":"integer","minimum":0,"maximum":20},"bathrooms":{"type":"integer","minimum":0,"maximum":20},"sizeSqm":{"type":"number","minimum":10,"maximum":5000},"askingPriceOMR":{"type":"number","minimum":1000,"maximum":1000000000},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished"]},"optionalAnnualServiceChargeOMR":{"type":"number","minimum":0,"maximum":1000000000},"optionalAnnualMaintenanceOMR":{"type":"number","minimum":0,"maximum":1000000000}},"required":["governorate","area","propertyType","sizeSqm","askingPriceOMR"],"additionalProperties":false,"examples":[{"governorate":"Muscat","area":"Al Mouj","propertyType":"apartment","bedrooms":2,"sizeSqm":130,"askingPriceOMR":118000}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"normalizedLocation":{"type":"object","properties":{"governorate":{"type":"string"},"wilayat":{"type":"string"},"area":{"type":"string"},"inputArea":{"type":"string"},"matchType":{"type":"string","enum":["exact","alias","unmatched"]},"supported":{"type":"boolean"}},"required":["governorate","wilayat","area","inputArea","matchType","supported"],"additionalProperties":false},"subjectProperty":{"type":"object","properties":{"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"sizeSqm":{"type":"number"},"askingPriceOMR":{"type":"number"},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished","unspecified"]}},"required":["propertyType","bedrooms","bathrooms","sizeSqm","askingPriceOMR","furnished"],"additionalProperties":false},"market":{"type":"object","properties":{"estimatedMonthlyRentOMR":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"estimatedAnnualRentOMR":{"type":["number","null"]},"comparableCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sampleSizeUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimatedMonthlyRentOMR","estimatedAnnualRentOMR","comparableCount","sampleSizeUsed","dataFreshnessDays"],"additionalProperties":false},"investment":{"type":"object","properties":{"grossYieldPct":{"type":["number","null"]},"estimatedOperatingCostOMR":{"type":"number"},"estimatedNetIncomeOMR":{"type":["number","null"]},"netYieldPct":{"type":["number","null"]}},"required":["grossYieldPct","estimatedOperatingCostOMR","estimatedNetIncomeOMR","netYieldPct"],"additionalProperties":false},"pricePosition":{"type":"object","properties":{"askingPricePerSqmOMR":{"type":"number"},"observedComparableRange":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"marketPosition":{"type":"string","enum":["below_market","at_market","above_market","insufficient_data"]}},"required":["askingPricePerSqmOMR","observedComparableRange","marketPosition"],"additionalProperties":false},"comparablesSummary":{"anyOf":[{"type":"object","properties":{"medianRentPerSqm":{"type":"number"},"lowRentPerSqm":{"type":"number"},"highRentPerSqm":{"type":"number"}},"required":["medianRentPerSqm","lowRentPerSqm","highRentPerSqm"],"additionalProperties":false},{"type":"null"}]},"riskFlags":{"type":"array","items":{"type":"string"}},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1},"level":{"type":"string","enum":["insufficient","low","medium","high"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["score","level","reasons"],"additionalProperties":false},"provenance":{"type":"array","items":{"type":"object","properties":{"sourceType":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]},"sourceName":{"type":"string"},"sourceDate":{"type":"string"},"recordCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceType","sourceName","sourceDate","recordCount"],"additionalProperties":false}},"assumptions":{"type":"array","items":{"type":"string"}},"insufficientMarketData":{"type":"boolean"},"unavailableOutputs":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","const":"OMR"},"dataQuality":{"type":"object","properties":{"latestDataDate":{"type":["string","null"]},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sampleSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceTypes":{"type":"array","items":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]}},"staleMarketData":{"type":"boolean"}},"required":["latestDataDate","dataFreshnessDays","sampleSize","sourceTypes","staleMarketData"],"additionalProperties":false}},"required":["normalizedLocation","subjectProperty","market","investment","pricePosition","comparablesSummary","riskFlags","confidence","provenance","assumptions","insufficientMarketData","unavailableOutputs","currency","dataQuality"],"additionalProperties":false}}],"meta":{"requestId":"example-request"}}}}}}}}}},"/agent.json":{"get":{"operationId":"agent_manifest","tags":["Agent"],"summary":"Full agent manifest","description":"Comprehensive, unauthenticated discovery document: product identity, every supported protocol (MCP, x402, REST), the OpenAPI URL, x402 terms and the complete tool catalog with full input/output JSON Schemas. No secrets.","security":[],"responses":{"200":{"description":"Agent manifest","content":{"application/json":{"schema":{"type":"object"},"examples":{"default":{"summary":"Example","value":{"name":"Rafid Property Intelligence","description":"Property and facility intelligence tools built for autonomous AI agents: discover a capability, pay per call over x402 (or authenticate with an API key), execute, get a structured result. Not designed primarily as a human dashboard product.","version":"0.1.0","audience":"ai-agents","protocols":[{"protocol":"mcp","role":"primary","transports":["stdio","http"],"remote":true,"endpoint":"/mcp","description":"Every capability exposed as an MCP tool with strict input/output schemas, over local stdio (`npm run mcp`) or the remote Streamable HTTP transport at /mcp."},{"protocol":"x402","role":"primary","enabled":true,"network":"eip155:8453","description":"Pay-per-call, no account or API key required."},{"protocol":"rest","role":"compatibility","description":"X-API-Key authenticated HTTP routes; the underlying transport MCP and the informational endpoints share, and a fallback for callers that can't do x402 yet."}],"interfaces":{"mcp":{"transports":["stdio","http"],"remote":true,"endpoint":"/mcp"},"openapi":"/openapi.json","docs":"/docs","rest":{"role":"compatibility","baseUrl":"/api/v1"}},"x402":{"enabled":true,"network":"eip155:8453","currency":"USD","facilitator":"coinbase-cdp","payTo":"0x29d4d3Ced89d7adcb0Ae47Ef6892CE24BD2b125f","info":"/api/v1/x402","status":"/api/v1/x402/status"},"currency":"USD","tools":[{"name":"analyze_property","description":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.","whenToUse":"Use when an agent needs financial metrics (yield, income, payback) for a single property.","useCases":["property investment analysis","rental yield check","single-property evaluation","buy vs. hold financial screening"],"price":0.01,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/property/analyze","x402Endpoint":"/api/v1/x402/property/analyze","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000}},"required":["propertyValue","annualRent"],"additionalProperties":false,"examples":[{"propertyValue":85000,"annualRent":7200,"serviceCharge":650,"maintenanceCost":400}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note"],"additionalProperties":false}},{"name":"compare_properties","description":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.","whenToUse":"Use when an agent must rank or choose between 2-20 candidate properties by net yield.","useCases":["property comparison","ranking multiple properties","portfolio shortlisting","choosing between investment options"],"price":0.03,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/property/compare","x402Endpoint":"/api/v1/x402/property/compare","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"annualRent":{"type":"number","minimum":0,"maximum":1000000000000},"serviceCharge":{"type":"number","minimum":0,"maximum":1000000000000},"maintenanceCost":{"type":"number","minimum":0,"maximum":1000000000000},"maintenance":{"description":"Legacy alias for maintenanceCost; supply only one","type":"number","minimum":0,"maximum":1000000000000},"vacancyRatePct":{"type":"number","minimum":0,"maximum":100},"otherAnnualCosts":{"type":"number","minimum":0,"maximum":1000000000000},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["propertyValue","annualRent","name"],"additionalProperties":false}}},"required":["properties"],"additionalProperties":false,"examples":[{"properties":[{"name":"A","propertyValue":85000,"annualRent":7200},{"name":"B","propertyValue":100000,"annualRent":7000}]}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"propertyValue":{"type":"number"},"annualRent":{"type":"number"},"grossAnnualIncome":{"type":"number"},"grossYield":{"type":"number"},"netYield":{"type":"number"},"annualOperatingCost":{"type":"number"},"annualNetIncome":{"type":"number"},"effectiveAnnualRent":{"type":"number"},"paybackYears":{"type":["number","null"]},"grossYieldPct":{"type":"number"},"netYieldPct":{"type":"number"},"annualOperatingCosts":{"type":"number"},"currency":{"type":"string","const":"OMR"},"note":{"type":"string"},"name":{"type":"string"}},"required":["propertyValue","annualRent","grossAnnualIncome","grossYield","netYield","annualOperatingCost","annualNetIncome","effectiveAnnualRent","paybackYears","grossYieldPct","netYieldPct","annualOperatingCosts","currency","note","name"],"additionalProperties":false}},"sortedByNetYield":{"type":"array","items":{"type":"string"}}},"required":["properties","sortedByNetYield"],"additionalProperties":false}},{"name":"estimate_maintenance","description":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.","whenToUse":"Use when an agent needs an annual maintenance reserve estimate for a property, not an actual inspection.","useCases":["maintenance budgeting","annual reserve estimation","facility cost planning","pre-purchase cost forecasting"],"price":0.02,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/maintenance/estimate","x402Endpoint":"/api/v1/x402/maintenance/estimate","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"propertyValue":{"type":"number","minimum":0.01,"maximum":1000000000000},"ageYears":{"type":"number","minimum":0,"maximum":200},"units":{"type":"integer","minimum":1,"maximum":10000},"annualRent":{"description":"Legacy input; unused in this value-based estimate","type":"number","minimum":0,"maximum":1000000000000},"assumptions":{"type":"object","properties":{"annualRatePct":{"type":"number","minimum":0,"maximum":100},"additionalUnitCost":{"type":"number","minimum":0,"maximum":1000000000000}},"additionalProperties":false}},"required":["propertyValue"],"additionalProperties":false,"examples":[{"propertyValue":100000,"ageYears":12,"units":1}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"estimatedAnnualMaintenance":{"type":"number"},"monthlyReserve":{"type":"number"},"maintenancePercentage":{"type":"number"},"currency":{"type":"string","const":"OMR"},"assumptionsUsed":{"type":"object","properties":{"ageYears":{"type":"number"},"units":{"type":"number"},"annualRatePct":{"type":"number"},"additionalUnitCost":{"type":"number"}},"required":["ageYears","units","annualRatePct","additionalUnitCost"],"additionalProperties":false},"methodology":{"type":"string"}},"required":["estimatedAnnualMaintenance","monthlyReserve","maintenancePercentage","currency","assumptionsUsed","methodology"],"additionalProperties":false}},{"name":"analyze_oman_property","description":"Analyze an Oman residential property using local rental comparables, market context and investment metrics.","whenToUse":"Use when an agent needs Oman-specific rental, yield, price-position or operating-cost analysis.","useCases":["Oman rental investment analysis","Muscat property market comparison","rental yield with local comparables","Oman price-per-sqm benchmarking"],"price":0.25,"currency":"USD","paymentProtocol":"x402","network":"eip155:8453","idempotent":true,"sideEffects":false,"endpoint":"/api/v1/oman/property/analyze","x402Endpoint":"/api/v1/x402/oman/property/analyze","method":"POST","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"governorate":{"type":"string","minLength":1,"maxLength":60},"wilayat":{"type":"string","minLength":1,"maxLength":60},"area":{"type":"string","minLength":1,"maxLength":80},"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":"integer","minimum":0,"maximum":20},"bathrooms":{"type":"integer","minimum":0,"maximum":20},"sizeSqm":{"type":"number","minimum":10,"maximum":5000},"askingPriceOMR":{"type":"number","minimum":1000,"maximum":1000000000},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished"]},"optionalAnnualServiceChargeOMR":{"type":"number","minimum":0,"maximum":1000000000},"optionalAnnualMaintenanceOMR":{"type":"number","minimum":0,"maximum":1000000000}},"required":["governorate","area","propertyType","sizeSqm","askingPriceOMR"],"additionalProperties":false,"examples":[{"governorate":"Muscat","area":"Al Mouj","propertyType":"apartment","bedrooms":2,"sizeSqm":130,"askingPriceOMR":118000}]},"outputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"normalizedLocation":{"type":"object","properties":{"governorate":{"type":"string"},"wilayat":{"type":"string"},"area":{"type":"string"},"inputArea":{"type":"string"},"matchType":{"type":"string","enum":["exact","alias","unmatched"]},"supported":{"type":"boolean"}},"required":["governorate","wilayat","area","inputArea","matchType","supported"],"additionalProperties":false},"subjectProperty":{"type":"object","properties":{"propertyType":{"type":"string","enum":["apartment","villa","townhouse"]},"bedrooms":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"sizeSqm":{"type":"number"},"askingPriceOMR":{"type":"number"},"furnished":{"type":"string","enum":["furnished","semi_furnished","unfurnished","unspecified"]}},"required":["propertyType","bedrooms","bathrooms","sizeSqm","askingPriceOMR","furnished"],"additionalProperties":false},"market":{"type":"object","properties":{"estimatedMonthlyRentOMR":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"estimatedAnnualRentOMR":{"type":["number","null"]},"comparableCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sampleSizeUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimatedMonthlyRentOMR","estimatedAnnualRentOMR","comparableCount","sampleSizeUsed","dataFreshnessDays"],"additionalProperties":false},"investment":{"type":"object","properties":{"grossYieldPct":{"type":["number","null"]},"estimatedOperatingCostOMR":{"type":"number"},"estimatedNetIncomeOMR":{"type":["number","null"]},"netYieldPct":{"type":["number","null"]}},"required":["grossYieldPct","estimatedOperatingCostOMR","estimatedNetIncomeOMR","netYieldPct"],"additionalProperties":false},"pricePosition":{"type":"object","properties":{"askingPricePerSqmOMR":{"type":"number"},"observedComparableRange":{"anyOf":[{"type":"object","properties":{"low":{"type":"number"},"median":{"type":"number"},"high":{"type":"number"}},"required":["low","median","high"],"additionalProperties":false},{"type":"null"}]},"marketPosition":{"type":"string","enum":["below_market","at_market","above_market","insufficient_data"]}},"required":["askingPricePerSqmOMR","observedComparableRange","marketPosition"],"additionalProperties":false},"comparablesSummary":{"anyOf":[{"type":"object","properties":{"medianRentPerSqm":{"type":"number"},"lowRentPerSqm":{"type":"number"},"highRentPerSqm":{"type":"number"}},"required":["medianRentPerSqm","lowRentPerSqm","highRentPerSqm"],"additionalProperties":false},{"type":"null"}]},"riskFlags":{"type":"array","items":{"type":"string"}},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1},"level":{"type":"string","enum":["insufficient","low","medium","high"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["score","level","reasons"],"additionalProperties":false},"provenance":{"type":"array","items":{"type":"object","properties":{"sourceType":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]},"sourceName":{"type":"string"},"sourceDate":{"type":"string"},"recordCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceType","sourceName","sourceDate","recordCount"],"additionalProperties":false}},"assumptions":{"type":"array","items":{"type":"string"}},"insufficientMarketData":{"type":"boolean"},"unavailableOutputs":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","const":"OMR"},"dataQuality":{"type":"object","properties":{"latestDataDate":{"type":["string","null"]},"dataFreshnessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sampleSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceTypes":{"type":"array","items":{"type":"string","enum":["official_statistics","listing_asking_price","manual_benchmark","partner_feed"]}},"staleMarketData":{"type":"boolean"}},"required":["latestDataDate","dataFreshnessDays","sampleSize","sourceTypes","staleMarketData"],"additionalProperties":false}},"required":["normalizedLocation","subjectProperty","market","investment","pricePosition","comparablesSummary","riskFlags","confidence","provenance","assumptions","insufficientMarketData","unavailableOutputs","currency","dataQuality"],"additionalProperties":false}}],"roadmap":[{"name":"estimate_property_rent","description":"Estimate achievable market rent for a property from comparable listings.","status":"planned"},{"name":"analyze_lease","description":"Extract and evaluate key terms, obligations and risk flags from a lease document.","status":"planned"},{"name":"check_contract_risk","description":"Flag risky or unusual clauses in a property-related contract.","status":"planned"},{"name":"diagnose_maintenance_issue","description":"Triage a described maintenance issue toward likely cause and urgency.","status":"planned"},{"name":"estimate_repair_cost","description":"Estimate the cost of a specific repair, as a calibrated alternative to the general maintenance reserve heuristic.","status":"planned"},{"name":"generate_property_report","description":"Compose a structured report document from one or more other tool results.","status":"planned"}],"wellKnown":["/.well-known/ai-plugin.json","/.well-known/agent.json"],"llmsTxt":"/llms.txt"}}}}}}}}},"/.well-known/ai-plugin.json":{"get":{"operationId":"ai_plugin_manifest","tags":["Agent"],"summary":"OpenAI-plugin-style manifest","description":"Manifest in the legacy OpenAI ChatGPT-plugin convention, for tooling that still discovers services this way.","security":[],"responses":{"200":{"description":"ai-plugin.json manifest","content":{"application/json":{"schema":{"type":"object"},"examples":{"default":{"summary":"Example","value":{"schema_version":"v1","name_for_human":"Rafid Property Intelligence","name_for_model":"rafid_property_intelligence","description_for_human":"Property investment analysis, property comparison, maintenance-reserve estimates, and Oman/Muscat-specific rental-comparable analysis. Pay per call, no account needed.","description_for_model":"Calculates property investment metrics (rental yield, income, simple payback), compares multiple properties by net yield, estimates an annual maintenance reserve, and (analyze_oman_property) analyzes a Muscat residential property against local rental/sale comparables with normalization, outlier removal, confidence scoring and provenance. All monetary property inputs and outputs are in OMR. Call GET /api/v1/capabilities first for exact input/output JSON Schemas, pricing and usage guidance per tool. Authenticate with an X-API-Key header, or call the unauthenticated /api/v1/x402/... twin of any route and pay per call on-chain via the x402 protocol (see GET /api/v1/x402 for current terms). These are calculations over the numbers/comparables supplied or looked up, not live market data (Oman comparable data is a curated MVP benchmark dataset — see its own response provenance) and not investment advice.","auth":{"type":"none"},"api":{"type":"openapi","url":"https://rafid-agent-api.vercel.app/openapi.json"},"logo_url":"","contact_email":"","legal_info_url":""}}}}}}}}},"/.well-known/agent.json":{"get":{"operationId":"agent_card","tags":["Agent"],"summary":"A2A-style Agent Card","description":"Agent Card in the Agent2Agent (A2A) protocol's convention at this well-known path, listing each tool as a skill.","security":[],"responses":{"200":{"description":"Agent Card","content":{"application/json":{"schema":{"type":"object"},"examples":{"default":{"summary":"Example","value":{"name":"Rafid Property Intelligence","description":"Property and facility intelligence tools built for autonomous AI agents: discover a capability, pay per call over x402 (or authenticate with an API key), execute, get a structured result. Not designed primarily as a human dashboard product.","url":"https://rafid-agent-api.vercel.app","provider":{"organization":"Rafid"},"version":"0.1.0","capabilities":{"streaming":false,"pushNotifications":false},"authentication":{"schemes":["x402","apiKey"]},"defaultInputModes":["application/json"],"defaultOutputModes":["application/json"],"skills":[{"id":"analyze_property","name":"analyze_property","description":"Calculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.","tags":["property investment analysis","rental yield check","single-property evaluation","buy vs. hold financial screening"],"examples":["{\"propertyValue\":85000,\"annualRent\":7200,\"serviceCharge\":650,\"maintenanceCost\":400}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"compare_properties","name":"compare_properties","description":"Compare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.","tags":["property comparison","ranking multiple properties","portfolio shortlisting","choosing between investment options"],"examples":["{\"properties\":[{\"name\":\"A\",\"propertyValue\":85000,\"annualRent\":7200},{\"name\":\"B\",\"propertyValue\":100000,\"annualRent\":7000}]}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"estimate_maintenance","name":"estimate_maintenance","description":"Estimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.","tags":["maintenance budgeting","annual reserve estimation","facility cost planning","pre-purchase cost forecasting"],"examples":["{\"propertyValue\":100000,\"ageYears\":12,\"units\":1}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"analyze_oman_property","name":"analyze_oman_property","description":"Analyze an Oman residential property using local rental comparables, market context and investment metrics.","tags":["Oman rental investment analysis","Muscat property market comparison","rental yield with local comparables","Oman price-per-sqm benchmarking"],"examples":["{\"governorate\":\"Muscat\",\"area\":\"Al Mouj\",\"propertyType\":\"apartment\",\"bedrooms\":2,\"sizeSqm\":130,\"askingPriceOMR\":118000}"],"inputModes":["application/json"],"outputModes":["application/json"]}]}}}}}}}}},"/mcp":{"post":{"operationId":"mcp_remote","tags":["Agent"],"summary":"Remote MCP transport (Streamable HTTP, JSON-RPC 2.0)","description":"Not a REST endpoint: this is the MCP Streamable HTTP transport, carrying JSON-RPC 2.0 requests (initialize, tools/list, tools/call, ...) per the Model Context Protocol specification, not an OpenAPI-shaped request/response. Stateless (no session ID), so every request is self-contained. See GET /api/v1/mcp/status to check whether this transport is live, and /llms.txt for a plain-text connection summary.","security":[],"requestBody":{"required":true,"description":"A JSON-RPC 2.0 request object.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"A JSON-RPC 2.0 response (or an SSE stream negotiated via the Accept header)."}}}},"/api/v1/mcp/status":{"get":{"operationId":"mcp_status","tags":["Agent"],"summary":"Factual MCP transport status","description":"Always-on status report for MCP connectivity: which transports are live (stdio always, http only when MCP_REMOTE_ENABLED=true), the tool count, and the remote endpoint path if any. No secret, no session data.","security":[],"responses":{"200":{"description":"MCP status","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"const":true},"data":{"type":"object","required":["enabled","transport","tools","endpoint"],"properties":{"enabled":{"type":"boolean"},"transport":{"type":"array","items":{"type":"string"}},"tools":{"type":"integer"},"endpoint":{"type":["string","null"]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"examples":{"default":{"summary":"Example","value":{"success":true,"data":{"enabled":true,"transport":["stdio","http"],"tools":4,"endpoint":"/mcp"},"meta":{"requestId":"example-request"}}}}}}}}}},"/llms.txt":{"get":{"operationId":"llms_txt","tags":["Agent"],"summary":"Plain-text briefing for LLM-based agents","description":"What Rafid does, every tool and how to call it, pricing, the x402 payment model and known limitations, in plain text for an agent that hasn't called a JSON endpoint yet.","security":[],"responses":{"200":{"description":"llms.txt","content":{"text/plain":{"schema":{"type":"string"},"example":"# Rafid Property Intelligence\n\n> Property and facility intelligence tools built for autonomous AI agents. Discover a\n> capability, pay per call over x402 (or authenticate with an API key), execute, get a\n> structured JSON result. This is a calculator over the numbers you send it, not a source of\n> live market data, and not investment advice. All monetary property inputs/outputs are OMR;\n> tool prices are USD.\n\n## How to call a tool\n\n1. Read GET /api/v1/capabilities for the exact JSON Schema, price and an example for every\n   tool (the machine-readable version of this file).\n2. Call POST /api/v1/<tool-path> with an X-API-Key header, OR call the unauthenticated\n   POST /api/v1/x402/<tool-path> twin and pay per call via the x402 protocol.\n3. Every response is { success: true, data: <output>, meta: { tool, price, currency } } on\n   success, or { success: false, error: { code, message } } on failure.\n\n## Tools\n\n## analyze_property\nCalculate gross/net rental yield, income, operating costs and simple payback in OMR. Calculations only.\nWhen to use: Use when an agent needs financial metrics (yield, income, payback) for a single property.\nPrice: $0.01 USD per call.\nAPI key route: POST /api/v1/property/analyze  (header: X-API-Key)\nx402 route:    POST /api/v1/x402/property/analyze  (no account — pay per call on-chain)\nMCP tool name: analyze_property\nExample request: {\"propertyValue\":85000,\"annualRent\":7200,\"serviceCharge\":650,\"maintenanceCost\":400}\n\n## compare_properties\nCompare 2–20 uniquely named properties in OMR using the same metrics; order by rounded net yield, preserving input order for ties.\nWhen to use: Use when an agent must rank or choose between 2-20 candidate properties by net yield.\nPrice: $0.03 USD per call.\nAPI key route: POST /api/v1/property/compare  (header: X-API-Key)\nx402 route:    POST /api/v1/x402/property/compare  (no account — pay per call on-chain)\nMCP tool name: compare_properties\nExample request: {\"properties\":[{\"name\":\"A\",\"propertyValue\":85000,\"annualRent\":7200},{\"name\":\"B\",\"propertyValue\":100000,\"annualRent\":7000}]}\n\n## estimate_maintenance\nEstimate an annual maintenance reserve in OMR from value, age and unit count with explicit optional assumptions. Uncalibrated heuristic, not a survey.\nWhen to use: Use when an agent needs an annual maintenance reserve estimate for a property, not an actual inspection.\nPrice: $0.02 USD per call.\nAPI key route: POST /api/v1/maintenance/estimate  (header: X-API-Key)\nx402 route:    POST /api/v1/x402/maintenance/estimate  (no account — pay per call on-chain)\nMCP tool name: estimate_maintenance\nExample request: {\"propertyValue\":100000,\"ageYears\":12,\"units\":1}\n\n## analyze_oman_property\nAnalyze an Oman residential property using local rental comparables, market context and investment metrics.\nWhen to use: Use when an agent needs Oman-specific rental, yield, price-position or operating-cost analysis.\nPrice: $0.25 USD per call.\nAPI key route: POST /api/v1/oman/property/analyze  (header: X-API-Key)\nx402 route:    POST /api/v1/x402/oman/property/analyze  (no account — pay per call on-chain)\nMCP tool name: analyze_oman_property\nExample request: {\"governorate\":\"Muscat\",\"area\":\"Al Mouj\",\"propertyType\":\"apartment\",\"bedrooms\":2,\"sizeSqm\":130,\"askingPriceOMR\":118000}\n\n## Payment (x402)\n\nx402 pay-per-call is enabled on this deployment (network: eip155:8453). Call any /api/v1/x402/... route without payment first to receive an HTTP 402 with machine-readable payment requirements (price, network, asset, receiving address), then retry with a valid X-PAYMENT header. See GET /api/v1/x402 for terms and GET /api/v1/x402/status for live, factual enforcement status.\n\nNo account, signup or dashboard is required for either access model.\n\n## Other machine-readable endpoints\n\n- GET /agent.json — full agent manifest (protocols, x402 terms, complete tool catalog)\n- GET /.well-known/ai-plugin.json — OpenAI-plugin-style manifest\n- GET /.well-known/agent.json — A2A-style Agent Card\n- GET /api/v1/capabilities — machine-first capability registry (schemas, pricing, when to use)\n- GET /openapi.json — full OpenAPI 3.1 document\n\n## Planned tools (not yet implemented — do not call these)\n\n- estimate_property_rent: Estimate achievable market rent for a property from comparable listings. (not yet implemented)\n- analyze_lease: Extract and evaluate key terms, obligations and risk flags from a lease document. (not yet implemented)\n- check_contract_risk: Flag risky or unusual clauses in a property-related contract. (not yet implemented)\n- diagnose_maintenance_issue: Triage a described maintenance issue toward likely cause and urgency. (not yet implemented)\n- estimate_repair_cost: Estimate the cost of a specific repair, as a calibrated alternative to the general maintenance reserve heuristic. (not yet implemented)\n- generate_property_report: Compose a structured report document from one or more other tool results. (not yet implemented)\n\n## analyze_oman_property coverage\n\nGovernorate: Muscat only. Supported areas: Al Mouj, Muscat Hills, Qurum, Bausher, Azaiba, Al Khuwair, Madinat Al Irfan, Ghubrah.\nAn unsupported governorate or an unrecognized area returns insufficientMarketData: true rather\nthan a guessed estimate — deterministic figures that need no market data (asking price per sqm,\noperating cost) are still returned. Apartments, villas and townhouses are supported; a property\ntype is never compared against a different one.\n\n## Limitations\n\n- analyze_property, compare_properties and estimate_maintenance are pure calculations over the\n  numbers supplied in the request; none of them fetch external data or perform an inspection.\n- estimate_maintenance is an uncalibrated heuristic, not a survey or a contractor estimate.\n- analyze_oman_property covers Muscat governorate only (see coverage above) and, for this MVP,\n  its comparable data is a curated/demo benchmark dataset (sourceType \"manual_benchmark\") — not\n  live listings, not official statistics, and not confirmed completed-transaction prices. Its own\n  response always states this in riskFlags/provenance; treat its market figures as illustrative\n  until a licensed/official feed is integrated.\n- Nothing here is financial, legal or investment advice.\n"}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Enter an active Rafid API key. Swagger UI sends it in the X-API-Key request header."}}}}