> ## Documentation Index
> Fetch the complete documentation index at: https://docs.majarrah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Decision

> Evaluate a property and get a structured verdict.

## Request body

<ParamField body="property" type="object" required>
  The property to evaluate.

  <Expandable title="property fields">
    <ParamField body="type" type="string" required>
      Property type. One of: `apartment`, `villa`, `land`, `commercial`, `office`
    </ParamField>

    <ParamField body="price" type="number" required>
      Asking price in SAR.
    </ParamField>

    <ParamField body="area" type="number" required>
      Total area in square meters.
    </ParamField>

    <ParamField body="bedrooms" type="number">
      Number of bedrooms.
    </ParamField>

    <ParamField body="bathrooms" type="number">
      Number of bathrooms.
    </ParamField>

    <ParamField body="floor" type="number">
      Floor number. Use `0` for ground floor.
    </ParamField>

    <ParamField body="age" type="number">
      Property age in years.
    </ParamField>

    <ParamField body="parking" type="boolean">
      Whether parking is available.
    </ParamField>

    <ParamField body="furnished" type="boolean">
      Whether the property is furnished.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="location" type="object" required>
  Property location.

  <Expandable title="location fields">
    <ParamField body="city" type="string" required>
      City name. E.g. `"Riyadh"`, `"Jeddah"`, `"Al Khobar"`.
    </ParamField>

    <ParamField body="district" type="string" required>
      District or neighbourhood. E.g. `"Al Malqa"`, `"Al Corniche"`.
    </ParamField>

    <ParamField body="lat" type="number">
      Latitude (optional, improves location scoring).
    </ParamField>

    <ParamField body="lng" type="number">
      Longitude (optional, improves location scoring).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reasoning" type="boolean" required>
  `false` - algorithmic scoring only (1 decision). Returns score and breakdown instantly.

  `true` - scoring + AI reasoning (3 decisions). Adds a `reasoning` object with English and Arabic explanations.
</ParamField>

***

## Response

<ResponseField name="verdict" type="string">
  `match`, `partial`, or `no_match`. Derived from `score`: 70+ is match, 40–69 is partial, below 40 is no match.
</ResponseField>

<ResponseField name="score" type="number">
  Overall score from 0 to 100.
</ResponseField>

<ResponseField name="breakdown" type="object">
  Per-bucket scores and statuses.

  <Expandable title="breakdown fields">
    <ResponseField name="price" type="object">
      `score` (0–100) and `status` (`pass`, `warn`, `fail`). Compares property price against market benchmarks.
    </ResponseField>

    <ResponseField name="location" type="object">
      `score` and `status`. Area demand and market trend.
    </ResponseField>

    <ResponseField name="size" type="object">
      `score` and `status`. Price per sqm vs. market average for the type and location.
    </ResponseField>

    <ResponseField name="details" type="object">
      `score` and `status`. Type-specific factors: bedrooms, floor, age, parking, etc.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="price_per_sqm" type="number">
  Calculated price per square meter for this property.
</ResponseField>

<ResponseField name="benchmark" type="object | null">
  MOJ market data used for price scoring. `null` if no benchmark exists for the given city/district.

  <Expandable title="benchmark fields">
    <ResponseField name="median_sqm" type="number">
      Median transaction price per sqm (SAR) for this city/district. The midpoint — half of transactions were above, half below.
    </ResponseField>

    <ResponseField name="p25_sqm" type="number">
      25th percentile price per sqm. Properties priced at or below this are considered well-priced.
    </ResponseField>

    <ResponseField name="p75_sqm" type="number">
      75th percentile price per sqm. Properties priced above this are considered expensive for the area.
    </ResponseField>

    <ResponseField name="year" type="number">
      Year of the benchmark data (MOJ transaction year).
    </ResponseField>

    <ResponseField name="transaction_count" type="number">
      Number of transactions used to compute the benchmark.
    </ResponseField>

    <ResponseField name="yoy_pct" type="number | null">
      Year-over-year price change percentage vs. the prior year. `null` if no prior-year data is available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reasoning" type="object">
  Only present when `reasoning: true`.

  <Expandable title="reasoning fields">
    <ResponseField name="reasoning_en" type="string">
      2–3 sentence investment rationale in English.
    </ResponseField>

    <ResponseField name="reasoning_ar" type="string">
      2–3 sentence investment rationale in Arabic.
    </ResponseField>

    <ResponseField name="key_factors" type="string[]">
      Up to 3 positive factors supporting the verdict.
    </ResponseField>

    <ResponseField name="risk_flags" type="string[]">
      Risk factors to be aware of.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="decisions_used" type="number">
  Decisions consumed by this request. `1` for scoring only, `3` for reasoning.
</ResponseField>

<ResponseField name="decisions_remaining" type="number">
  Your remaining decision balance after this request.
</ResponseField>

***

## Examples

<CodeGroup>
  ```bash Apartment - scoring only theme={null}
  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,
        "area": 95,
        "bedrooms": 2,
        "bathrooms": 2,
        "floor": 8
      },
      "location": {
        "city": "Al Khobar",
        "district": "Al Corniche"
      },
      "reasoning": false
    }'
  ```

  ```bash Villa - with reasoning theme={null}
  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,
        "area": 420,
        "bedrooms": 4,
        "bathrooms": 5
      },
      "location": {
        "city": "Riyadh",
        "district": "Al Nakheel"
      },
      "reasoning": true
    }'
  ```

  ```bash Land theme={null}
  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,
        "area": 600
      },
      "location": {
        "city": "Riyadh",
        "district": "North Riyadh"
      },
      "reasoning": false
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 - reasoning: false theme={null}
  {
    "verdict": "match",
    "score": 76,
    "breakdown": {
      "price":    { "score": 85, "status": "pass" },
      "location": { "score": 90, "status": "pass" },
      "size":     { "score": 82, "status": "pass" },
      "details":  { "score": 65, "status": "warn" }
    },
    "price_per_sqm": 8947,
    "benchmark": {
      "median_sqm": 9100,
      "p25_sqm": 8200,
      "p75_sqm": 10500,
      "year": 2025,
      "transaction_count": 143,
      "yoy_pct": 4
    },
    "decisions_used": 1,
    "decisions_remaining": 99
  }
  ```

  ```json 200 - reasoning: true theme={null}
  {
    "verdict": "match",
    "score": 76,
    "breakdown": {
      "price":    { "score": 85, "status": "pass" },
      "location": { "score": 90, "status": "pass" },
      "size":     { "score": 82, "status": "pass" },
      "details":  { "score": 65, "status": "warn" }
    },
    "price_per_sqm": 8947,
    "benchmark": {
      "median_sqm": 9100,
      "p25_sqm": 8200,
      "p75_sqm": 10500,
      "year": 2025,
      "transaction_count": 143,
      "yoy_pct": 4
    },
    "reasoning": {
      "reasoning_en": "Strong fit overall. Priced 2% below the Al Corniche median of 9,100 SAR/sqm. The Al Khobar corniche commands consistent demand and saw 4% YoY price growth in 2025. Two bedrooms at 95 sqm is above the area median for this price bracket.",
      "reasoning_ar": "مطابقة قوية بشكل عام. السعر أقل بنسبة 2% من متوسط الكورنيش البالغ 9,100 ريال/م². يشهد كورنيش الخبر طلباً ثابتاً وارتفع سعره 4% سنوياً في 2025. غرفتان على 95م² تفوق متوسط المنطقة في هذه الفئة السعرية.",
      "key_factors": ["Priced below area median", "Strong YoY price growth", "High-demand location"],
      "risk_flags": ["Limited transaction count in district"]
    },
    "decisions_used": 3,
    "decisions_remaining": 97
  }
  ```

  ```json 401 - Invalid API key theme={null}
  {
    "error": "invalid_api_key",
    "message": "Provide a valid Bearer token. API keys start with sk- and can be created in your dashboard."
  }
  ```

  ```json 402 - Insufficient decisions theme={null}
  {
    "error": "insufficient_decisions",
    "message": "This request requires 3 decisions. Your workspace has 1. Purchase more at www.majarrah.io.",
    "required": 3,
    "balance": 1
  }
  ```

  ```json 422 - Validation error theme={null}
  {
    "error": "validation_error",
    "message": "property.area must be a positive number (sqm).",
    "field": "property.area"
  }
  ```
</ResponseExample>