All endpoints are under /api, take and return JSON, and are implemented in src/app/api. Money is always in minor units (baisa for OMR) in bodies and answers; only the public search takes prices in major units in its query string.
Conventions
- Errors have one shape:
{"error": {"code": "validation", "message": "price: Too small..."}}with the matching HTTP status.
| Status | Codes |
|---|---|
| 400 | bad_json, bad_form |
| 401 | unauthorized, invalid_credentials |
| 403 | forbidden (role), demo_mode |
| 404 | not_found, property_not_found (also for records of another agent) |
| 409 | bad_transition, email_taken, slug_taken, has_listings |
| 413 / 415 | too_large, unsupported_type |
| 422 | validation, invalid_phone, past_date, too_far, outside_hours, unknown_area, unknown_agent, wrong_password, bad_image |
| 429 | rate_limited |
| 502 / 503 | ai_failed, ai_not_configured |
- Dashboard endpoints need the session cookie from
POST /api/auth/login. Calls that change data are refused in demo mode. - PATCH endpoints change only the fields present in the body.
- Scope: for agents, lists contain only their own records and single records of others answer 404.
Public
| Method and path | What | Notes |
|---|---|---|
GET /api/properties |
Search | Query: purpose, type, area (slug), governorate, minPrice, maxPrice (OMR), beds, baths, furnished, amenities (comma list), q, featured=1, ids, agent (slug), sort (newest, price_asc, price_desc, size_desc), page, perPage (max 48). Answers {items, total, page, pages, currency, currencyDecimals}. 120/min per IP. |
GET /api/properties/{slug} |
One listing | {property, similar, currency, currencyDecimals}; property.around has places, moments, lifeAr/lifeEn. 404 unless PUBLISHED or UNDER_OFFER. |
GET /api/compare?ids=a,b,c |
Compare / saved | Up to 3 listings with details, or 50 cards with cards=1. missing lists ids no longer public. |
GET /api/areas |
Areas | Visible areas with places and live listing counts. |
GET /api/agents, GET /api/agents/{slug} |
Agents | Staff shown on the website, and one agent with their live listings. |
GET /api/agency |
Agency details | Names, contact, currency. |
POST /api/inquiries |
Ask a question | {name, phone, email?, message, propertyId?, locale} → 201 {code}. 5/min per IP. |
POST /api/viewings |
Request a viewing | {name, phone, email?, propertyId, preferredDate: "YYYY-MM-DD", preferredTime: "HH:MM", message?, locale} → 201 {code}. Today to 60 days ahead, 08:00 to 20:00. |
Session
| Method and path | What |
|---|---|
POST /api/auth/login |
{email, password} → sets the cookie, {user}. 10/min per IP, 8 per 15 min per email. |
POST /api/auth/logout |
Clears the cookie. |
GET /api/auth/me |
{user, demoMode}. |
Dashboard
| Method and path | Who | What |
|---|---|---|
GET /api/dashboard/stats |
all | Overview: counts, recentLeads, upcomingViewings, byArea, recentlyUpdated. |
GET /api/dashboard/properties |
all | Query status, purpose, type, area (id), agent (id or unassigned), q, page; 25 per page. |
POST /api/dashboard/properties |
all | Create. Body: titleAr, titleEn, descAr, descEn, purpose, type, status (DRAFT/PUBLISHED), price, bedrooms, bathrooms, areaM2, plotM2, furnished, yearBuilt, amenities[], addressAr, addressEn, areaId, agentId (admins), featured (admins), images: [{url, virtual}]. |
GET/PATCH/DELETE /api/dashboard/properties/{id} |
own / admins | Read, change any subset (status flow enforced), delete (agents: own drafts). |
POST /api/dashboard/upload |
all | Multipart, one or more file fields → 201 {urls}. |
GET /api/dashboard/leads |
own / admins | Query kind, status, agent, property, q, page. |
GET/PATCH /api/dashboard/leads/{id} |
own / admins | Read with notes and viewings; change status (pipeline) and agentId (admins). |
POST /api/dashboard/leads/{id}/notes |
own / admins | {body} adds a note. |
GET /api/dashboard/viewings |
own / admins | Query from, to, status, agent. |
POST /api/dashboard/viewings |
own listings / admins | {propertyId, leadId?, name, phone, date, time, status?, note?, agentId?}. |
PATCH /api/dashboard/viewings/{id} |
own / admins | status (viewing flow), date, time, note, agentId (admins). |
POST /api/dashboard/ai/listing |
all | Listing writer. See AI assistant. |
POST /api/dashboard/ai/ask |
all | Questions over listings. |
POST /api/dashboard/ai/staging |
all | See AI staging studio. |
GET/POST /api/dashboard/areas, PATCH/DELETE /api/dashboard/areas/{id} |
read: all; change: admins | Areas with places: [{kind, nameAr, nameEn, minutes}]. |
GET/POST /api/dashboard/agents, PATCH/DELETE /api/dashboard/agents/{id} |
read: all; change: admins | Team accounts. Owner manages admins and agents, admins manage agents. |
GET /api/dashboard/roles |
all | Roles and the permission matrix. |
GET/PATCH /api/dashboard/settings |
read: all; change: owner | Agency settings. |
GET/PATCH /api/dashboard/me |
all | Own profile; a new password needs currentPassword. |
Example
# sign in and keep the cookie
curl -c jar -H "Content-Type: application/json" \
-d '{"email":"owner@dar.test","password":"dar-demo-2026"}' http://localhost:3303/api/auth/login
# mark a listing under offer (nothing else changes)
curl -b jar -X PATCH -H "Content-Type: application/json" \
-d '{"status":"UNDER_OFFER"}' http://localhost:3303/api/dashboard/properties/<id>