Create a Decision
curl --request POST \
--url https://api.majarrah.io/v1/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"property": {
"type": "<string>",
"price": 123,
"location": "<string>",
"size_sqm": 123
},
"reasoning": true,
"purpose": "<string>",
"budget": 123,
"min_roi": 123,
"context": "<string>",
"language": "<string>"
}
'import requests
url = "https://api.majarrah.io/v1/decisions"
payload = {
"property": {
"type": "<string>",
"price": 123,
"location": "<string>",
"size_sqm": 123
},
"reasoning": True,
"purpose": "<string>",
"budget": 123,
"min_roi": 123,
"context": "<string>",
"language": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
property: {type: '<string>', price: 123, location: '<string>', size_sqm: 123},
reasoning: true,
purpose: '<string>',
budget: 123,
min_roi: 123,
context: '<string>',
language: '<string>'
})
};
fetch('https://api.majarrah.io/v1/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.majarrah.io/v1/decisions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'property' => [
'type' => '<string>',
'price' => 123,
'location' => '<string>',
'size_sqm' => 123
],
'reasoning' => true,
'purpose' => '<string>',
'budget' => 123,
'min_roi' => 123,
'context' => '<string>',
'language' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.majarrah.io/v1/decisions"
payload := strings.NewReader("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"location\": \"<string>\",\n \"size_sqm\": 123\n },\n \"reasoning\": true,\n \"purpose\": \"<string>\",\n \"budget\": 123,\n \"min_roi\": 123,\n \"context\": \"<string>\",\n \"language\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.majarrah.io/v1/decisions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"location\": \"<string>\",\n \"size_sqm\": 123\n },\n \"reasoning\": true,\n \"purpose\": \"<string>\",\n \"budget\": 123,\n \"min_roi\": 123,\n \"context\": \"<string>\",\n \"language\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.majarrah.io/v1/decisions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"location\": \"<string>\",\n \"size_sqm\": 123\n },\n \"reasoning\": true,\n \"purpose\": \"<string>\",\n \"budget\": 123,\n \"min_roi\": 123,\n \"context\": \"<string>\",\n \"language\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"verdict": "match",
"score": 81,
"confidence": "high",
"breakdown": {
"price": { "score": 88, "status": "pass" },
"location": { "score": 92, "status": "pass" },
"size": { "score": 74, "status": "pass" },
"details": { "score": 70, "status": "pass" }
},
"credits_used": 1,
"credits_remaining": 49
}
{
"verdict": "match",
"score": 81,
"confidence": "high",
"breakdown": {
"price": { "score": 88, "status": "pass" },
"location": { "score": 92, "status": "pass" },
"size": { "score": 74, "status": "pass" },
"details": { "score": 70, "status": "pass" }
},
"reasoning": "Strong fit overall. Priced 4% below the area average for similar apartments in Dubai Marina. Floor 8 with elevator is favorable. Two bedrooms at 95 sqm is above the area median for this price bracket.",
"credits_used": 3,
"credits_remaining": 47
}
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "You don't have enough credits for this request.",
"details": {
"credits_required": 3,
"credits_remaining": 1
}
}
}
{
"error": {
"code": "MISSING_REQUIRED_FIELDS",
"message": "Some required fields are missing.",
"details": {
"missing": ["property.bedrooms", "property.elevator_available"]
}
}
}
Decisions
Create a Decision
Evaluate a property and get a structured verdict.
POST
/
decisions
Create a Decision
curl --request POST \
--url https://api.majarrah.io/v1/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"property": {
"type": "<string>",
"price": 123,
"location": "<string>",
"size_sqm": 123
},
"reasoning": true,
"purpose": "<string>",
"budget": 123,
"min_roi": 123,
"context": "<string>",
"language": "<string>"
}
'import requests
url = "https://api.majarrah.io/v1/decisions"
payload = {
"property": {
"type": "<string>",
"price": 123,
"location": "<string>",
"size_sqm": 123
},
"reasoning": True,
"purpose": "<string>",
"budget": 123,
"min_roi": 123,
"context": "<string>",
"language": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
property: {type: '<string>', price: 123, location: '<string>', size_sqm: 123},
reasoning: true,
purpose: '<string>',
budget: 123,
min_roi: 123,
context: '<string>',
language: '<string>'
})
};
fetch('https://api.majarrah.io/v1/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.majarrah.io/v1/decisions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'property' => [
'type' => '<string>',
'price' => 123,
'location' => '<string>',
'size_sqm' => 123
],
'reasoning' => true,
'purpose' => '<string>',
'budget' => 123,
'min_roi' => 123,
'context' => '<string>',
'language' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.majarrah.io/v1/decisions"
payload := strings.NewReader("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"location\": \"<string>\",\n \"size_sqm\": 123\n },\n \"reasoning\": true,\n \"purpose\": \"<string>\",\n \"budget\": 123,\n \"min_roi\": 123,\n \"context\": \"<string>\",\n \"language\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.majarrah.io/v1/decisions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"location\": \"<string>\",\n \"size_sqm\": 123\n },\n \"reasoning\": true,\n \"purpose\": \"<string>\",\n \"budget\": 123,\n \"min_roi\": 123,\n \"context\": \"<string>\",\n \"language\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.majarrah.io/v1/decisions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"location\": \"<string>\",\n \"size_sqm\": 123\n },\n \"reasoning\": true,\n \"purpose\": \"<string>\",\n \"budget\": 123,\n \"min_roi\": 123,\n \"context\": \"<string>\",\n \"language\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"verdict": "match",
"score": 81,
"confidence": "high",
"breakdown": {
"price": { "score": 88, "status": "pass" },
"location": { "score": 92, "status": "pass" },
"size": { "score": 74, "status": "pass" },
"details": { "score": 70, "status": "pass" }
},
"credits_used": 1,
"credits_remaining": 49
}
{
"verdict": "match",
"score": 81,
"confidence": "high",
"breakdown": {
"price": { "score": 88, "status": "pass" },
"location": { "score": 92, "status": "pass" },
"size": { "score": 74, "status": "pass" },
"details": { "score": 70, "status": "pass" }
},
"reasoning": "Strong fit overall. Priced 4% below the area average for similar apartments in Dubai Marina. Floor 8 with elevator is favorable. Two bedrooms at 95 sqm is above the area median for this price bracket.",
"credits_used": 3,
"credits_remaining": 47
}
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "You don't have enough credits for this request.",
"details": {
"credits_required": 3,
"credits_remaining": 1
}
}
}
{
"error": {
"code": "MISSING_REQUIRED_FIELDS",
"message": "Some required fields are missing.",
"details": {
"missing": ["property.bedrooms", "property.elevator_available"]
}
}
}
Request body
Always required
object
required
The property to evaluate.
boolean
required
false - scoring engine only (1 credit). Returns score and breakdown, no explanation.true - scoring engine + AI reasoning (3 credits). Adds a reasoning string to the response.Type-specific required fields
- apartment
- villa
- land
- shop / office
number
required
Number of bedrooms.
number
required
Number of bathrooms.
number
required
Floor number. Use
0 for ground floor.boolean
required
Whether the building has a working elevator.
string
required
Land use classification. One of:
residential, commercial, industrialnumber
required
Floor number. Use
0 for ground floor.Optional
string
Buyer intent.
own_use or investment. Shapes how the scoring weights price vs. ROI.number
Maximum budget. When provided, price scoring is relative to this value.
number
Minimum acceptable ROI percentage. Only relevant when
purpose is investment.string
Free-text context for the AI. Only used when
reasoning: true. E.g. "relocating from Riyadh, needs school proximity".string
default:"ar"
Response language for the
reasoning field. ar or en. Only used when reasoning: true.Response
string
match, partial, or no_match. Derived from score: 70+ is match, 40-69 is partial, below 40 is no match.number
Overall score from 0 to 100.
string
high, medium, or low. Reflects how much data was provided - more optional fields raise confidence.object
Per-bucket scores and statuses.
Show breakdown fields
Show breakdown fields
object
score (0-100) and status (pass, warn, fail). Compares property price against market benchmarks.object
Area demand, trend, and match to any
location_preferences.object
Price per sqm vs. market average for the type and location.
object
Type-specific factors: bedrooms, floor, elevator, zoning, etc.
string
Plain-language explanation of the verdict. Only present when
reasoning: true.number
Credits consumed by this request.
1 for scoring only, 3 for reasoning.number
Your remaining decision balance after this request.
Examples
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "apartment",
"price": 850000,
"location": "Dubai Marina",
"size_sqm": 95,
"bedrooms": 2,
"bathrooms": 2,
"floor": 8,
"elevator_available": true
},
"reasoning": false,
"purpose": "investment",
"budget": 900000
}'
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "villa",
"price": 2100000,
"location": "Al Nakheel, Riyadh",
"size_sqm": 420,
"bedrooms": 4,
"bathrooms": 5
},
"reasoning": true,
"purpose": "own_use",
"language": "en",
"context": "family of 5, need garden, school proximity important"
}'
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "land",
"price": 500000,
"location": "North Riyadh",
"size_sqm": 600,
"zoning": "residential"
},
"reasoning": false,
"purpose": "investment",
"min_roi": 8
}'
{
"verdict": "match",
"score": 81,
"confidence": "high",
"breakdown": {
"price": { "score": 88, "status": "pass" },
"location": { "score": 92, "status": "pass" },
"size": { "score": 74, "status": "pass" },
"details": { "score": 70, "status": "pass" }
},
"credits_used": 1,
"credits_remaining": 49
}
{
"verdict": "match",
"score": 81,
"confidence": "high",
"breakdown": {
"price": { "score": 88, "status": "pass" },
"location": { "score": 92, "status": "pass" },
"size": { "score": 74, "status": "pass" },
"details": { "score": 70, "status": "pass" }
},
"reasoning": "Strong fit overall. Priced 4% below the area average for similar apartments in Dubai Marina. Floor 8 with elevator is favorable. Two bedrooms at 95 sqm is above the area median for this price bracket.",
"credits_used": 3,
"credits_remaining": 47
}
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "You don't have enough credits for this request.",
"details": {
"credits_required": 3,
"credits_remaining": 1
}
}
}
{
"error": {
"code": "MISSING_REQUIRED_FIELDS",
"message": "Some required fields are missing.",
"details": {
"missing": ["property.bedrooms", "property.elevator_available"]
}
}
}