For: Full Stack · Backend API

API reference

Every endpoint, its parameters, its answers and who may call it.

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>