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). Photographs 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 whole US dollars, and dates are company calendar days written YYYY-MM-DD.

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. message is a sentence in the request's language, code the untranslated key behind it, and a refusal that names something adds the values behind its sentence in details:

{
  "success": false,
  "data": null,
  "message": "Booking B0021 already holds some of these nights.",
  "code": "dates_taken",
  "details": { "held_by": "booking", "reference": "B0021" }
}

A body the validation pipe refuses carries code: "validation_failed" and errors, keyed by each field's full name:

{
  "success": false,
  "data": null,
  "message": "guest_email must be an email",
  "errors": { "guest_email": ["guest_email must be an email"] },
  "code": "validation_failed"
}

• Branch on code, never on the sentence, which changes with the language. Booking and availability refusals carry codes such as dates_taken, min_nights, capacity, cancellation_window_passed, awaiting_payment and payment_method_unavailable, and a limit rate_limited.
• errors appears on a validation failure, with the problems under the field's name as the request spelled it (check_in, guest_email). 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.
• Nights already held answer 409, a booking step from the wrong status 422, and a request over a limit 429.

Lists and paging

{ "data": [ ], "page": 1, "page_size": 6, "total": 12, "total_pages": 2 }

• Stays, bookings, inquiries and reviews page with page and page_size: 6 stays a page on the website (at most 24), 20 in the dashboard (at most 50), 10 bookings and 20 inquiries (at most 50 each), 8 reviews. The dashboard's lists also return counts per status.
• Admins, roles and settings page with page and page_count (settings also take page_size), 10 by default and at most 100, and answer { data, page, limit, total, totalPages }.
• The website's stay 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. Stays, destinations and the home page questions 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@hollina.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/bookings/manage -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.
• Guests have no accounts. A guest's booking routes take the booking's access_token as ?token=, or the email it was made with as ?email=; a wrong pair answers 404.

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 32 permissions and the two seeded roles are listed in Admins, roles and permissions.

Stays on the website

Destinations, questions and the company's settings

Bookings

• A repeated client_token returns the first booking's receipt instead of making a second one, and a filled company field is treated as a bot: the answer looks the same, and nothing is stored.
• A payment_method that GET /api/payments/methods does not list (PayPal with only Stripe configured, card with only PayPal, pay on arrival with its setting off) answers 422 with payment_method_unavailable, before anything is written.
• The nights are checked when the booking is written: held nights answer 409 with dates_taken, and a stay's minimum, its capacity or a past check-in 422 with the reason.
• A hosted method answers pending with a redirect_url to Stripe or PayPal; the booking is confirmed only by the processor's webhook or the PayPal capture.

Questions to the host

• A repeated client_token returns the first submission instead of storing a second one, and a filled company field is treated as a bot.
• Each address may send five bookings, five questions and five reviews in ten minutes; the next answers 429.

Managing stays

The calendar and blocked dates

Bookings, inquiries and reviews

Destinations, questions 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

MCP server

Live updates over WebSocket

Demo mode routes