API reference

Base URL and response format

Every route is served under the /api prefix. Locally the base URL is http://localhost:8000/api. On a server it is your API's address followed by /api, the same value both frontends read from NEXT_PUBLIC_API_BASE_URL (Environment variables). Photos are served outside the prefix, at /media/….

The website's routes are public; the dashboard's need an admin's bearer token, and most also a permission. Request bodies are JSON, except file uploads. Every answer comes in the same envelope:

{
  "success": true,
  "data": { },
  "message": ""
}

data holds the result. message is a short sentence some writes fill in, in the request's language, and empty otherwise. Prices are decimal numbers in the property's currency.

The health check needs no token:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

When the database cannot be read it still answers 200, with "status":"degraded" and "database":"down". The Docker image's health check reads that field.

Errors

A failure keeps the envelope, with success: false and the HTTP status:

{
  "success": false,
  "data": null,
  "message": "…",
  "errors": { "email": ["…"] }
}

• message is a sentence in the request's language.
• errors appears on a validation failure, with the problems per field, keyed by the path the client sent (such as title.en). An unknown field in a body is refused.
• A guarded route with no token, or an expired one, answers 401; a token without the permission answers 403.
• A request over a limit answers 429.

Lists and paging

{ "data": [ ], "page": 1, "limit": 12, "total": 15, "totalPages": 2 }

• Properties, inquiries and viewings page with page and page_size: 12 a page by default on the website (at most 24), 10 in the dashboard (at most 50). The dashboard's lists also return their counts per status.
• Admins, roles and settings page with page and page_count.
• Unless the route has its own order, rows come newest-updated first, with the id as a tiebreaker, so paging is stable.
• The website's property filters are validated: an unknown value is refused with 400 rather than ignored, while a key the API does not read is ignored, so a shared link with extra parameters still works.

Language

Send Accept-Language: ar for Arabic messages; anything else answers in English. Properties and neighborhoods carry both languages as { "en": "…", "ar": "…" } whatever the header says, and the client picks one.

Signing in

1. 01

   Sign in as an admin

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@velra.example","password":"Admin@123"}'

   data.access_token is the token, with token_type Bearer and the admin with their roles and permissions. The token lasts JWT_EXPIRATION, 7d by default, and expires_in reports that value as written. GET /api/auth/me returns the signed-in admin with their roles and permissions.
2. 02

   Call a protected route

   TerminalCopy

   curl http://localhost:8000/api/leads -H "Authorization: Bearer YOUR_TOKEN"

• An unknown email and a wrong password both answer 401 with the same message.
• Ten failed sign-ins from one address within 15 minutes answer 429 until the oldest failure is 15 minutes old (RATE_LIMIT_LOGIN). Successful sign-ins are not counted.
• There is no sign-up and no sign-out route: accounts come from the seed or from Admin management, and a client signs out by forgetting its token.

Permissions

Dashboard routes check a permission named <area>.<action>. An admin holds every permission of every role they have, and a route that names several accepts any one of them. The 31 permissions and the two seeded roles are listed in Admins, roles and permissions.

Properties on the website

Neighborhoods and the agency's settings

The contact form and viewing requests

• A repeated client_token returns the first submission's receipt instead of storing a second one.
• A filled company field is treated as a bot: the answer looks the same, and nothing is stored.
• A viewing must start at least an hour ahead, in Asia/Dubai time; sooner answers 400 with preferred_time_too_soon on preferred_at.
• Each address may send five of each in ten minutes; the next answers 429.

Managing properties

Inquiries and viewings

Neighborhoods and settings

Admins and roles

Notifications and uploads

An upload has no permission of its own: what the file becomes is checked by the route that saves it. Notifications are kept for 30 days.

Limits per address

A request over a limit answers 429. The counts live in the API's memory, so a restart clears them. Behind a reverse proxy, set TRUST_PROXY so each visitor is counted on their own address.

AI assistant and its conversations

Staging studio

MCP server

Live updates over WebSocket

Demo mode route