All endpoints take and return JSON. Money is in the currency's smallest unit (baisa for OMR), dates are YYYY-MM-DD. Errors look like this:
{ "error": { "code": "unavailable", "message": "Some of these nights are already booked.", "detail": { "nights": ["2026-11-06"] } } }
| Status | When |
|---|---|
400 bad_json |
the body is not JSON |
401 unauthorized |
dashboard endpoint without a session |
403 forbidden |
the role lacks the permission |
404 not_found |
unknown item, or outside a host's stays |
| 409 | a rule refused it: unavailable, bad_transition, too_early, already_requested, last_owner, has_bookings, ... |
422 validation |
a field is missing or wrong (the message lists them); also quote rules such as min_nights |
429 rate_limited |
too many requests from this visitor |
| 502/503 | payment or AI provider problem, or AI not configured (ai_disabled) |
Public
| Method and path | What it does |
|---|---|
GET /api/stays |
Stays. Query: destination, type (CHALET, VILLA, CABIN, BEACH_HOUSE, DESERT_CAMP), guests, checkIn + checkOut, minPrice/maxPrice (OMR a night), amenities=pool,wifi, slugs=a,b, sort (recommended, price_asc, price_desc, rating, guests). With dates: only free stays, each with quote and perNight |
GET /api/stays/{slug} |
One stay with seasons, plus published reviews |
GET /api/stays/{slug}/availability?from=&days= |
taken: booked or blocked nights in the window (max 120 days) |
GET /api/stays/{slug}/quote?checkIn=&checkOut=&guests= |
quote: lines (one per night with its rate and season), nightsTotal, cleaningFee, tax, total, minNights |
GET /api/destinations |
Destinations with stay count and lowest rate |
POST /api/bookings |
{stayId, checkIn, checkOut, guests, guestName, email, phone, country, notes, paymentMethod: "CARD" or "ON_ARRIVAL", locale, acceptTerms: true} → 201 {code, status, payUrl?} |
GET /api/bookings/{code} |
Confirmation: stay, dates, total, status (no contact details) |
POST /api/bookings/lookup |
{code, contact} (email or phone) → the booking with masked contact, nightly prices, door code when due, canCancel, canReview, timeline |
POST /api/bookings/cancel |
{code, contact, reason} → cancellation request |
POST /api/reviews |
{code, contact, rating 1-5, text} for a completed stay, one per booking |
POST /api/inquiries |
{name, email, phone?, stayId? (id or slug), checkIn?, checkOut?, guests?, message, locale} |
GET /api/payments/thawani/return?booking= |
Where Thawani sends the guest back; checks the payment with Thawani |
Example:
curl "http://localhost:3304/api/stays/juniper-cabin/quote?checkIn=2026-11-05&checkOut=2026-11-08&guests=2"
Session
| Method and path | What it does |
|---|---|
POST /api/auth/login |
{email, password} → sets the nuzul_session cookie (httpOnly, 12 h) |
POST /api/auth/logout |
Clears it |
Dashboard
Permissions are those of src/lib/roles.ts (Booking dashboard). Hosts only reach their own stays.
| Method and path | Permission | What it does |
|---|---|---|
GET /api/dashboard/stats |
overview.view | Everything on the overview |
GET /api/dashboard/calendar?from=&days= |
calendar.view | Stays × nights (max 62 days) with booking or block per taken night and the price of each night |
POST /api/dashboard/blocks |
calendar.block | {stayId, startDate, endDate, note}; endDate is the morning after the last blocked night. 409 with detail.nights if any is taken |
DELETE /api/dashboard/blocks/{id} |
calendar.block | Open the nights again |
GET /api/dashboard/bookings |
bookings.view | Query: status (or CANCEL_REQUESTED), stayId, q, when (upcoming, past, all), page (50 per page) |
POST /api/dashboard/bookings |
bookings.create | Manual booking, confirmed at once: {stayId, checkIn, checkOut, guests, guestName, email, phone, country, notes, paid} |
GET /api/dashboard/bookings/{id} |
bookings.view | Full booking with nightly prices, door code, timeline |
PATCH /api/dashboard/bookings/{id} |
see below | status (bookings.status; CANCELLED needs bookings.cancel), note, paymentStatus (bookings.payment), internalNote, cancelRequested: false (bookings.cancel) |
GET /api/dashboard/stays |
stays.view | Stays (hidden too) with host and upcoming count; hosts to choose from |
POST /api/dashboard/stays |
stays.edit | New stay |
GET/PATCH/DELETE /api/dashboard/stays/{id} |
stays.view / stays.edit | PATCH changes only the fields sent; seasons replaces all seasons. DELETE only without bookings |
GET/POST /api/dashboard/destinations, PATCH/DELETE /api/dashboard/destinations/{id} |
stays.view / stays.edit | Destinations |
GET /api/dashboard/inquiries?status=, PATCH .../{id} |
inquiries.manage | {status: NEW, ANSWERED, CLOSED, note} |
GET /api/dashboard/reviews?status=&stayId=, PATCH .../{id} |
reviews.reply | {reply}; {status: PUBLISHED, HIDDEN, PENDING} needs reviews.moderate |
POST /api/dashboard/ai/ask |
ai.use | {question, history?, locale} → {answer} |
POST /api/dashboard/ai/describe |
stays.edit | {nameAr, nameEn, type, destinationId, amenities, notes} → {suggestion: {summaryAr, summaryEn, descAr, descEn}} |
GET /api/dashboard/settings |
signed in | Company settings and whether Thawani keys are set |
PATCH /api/dashboard/settings |
settings.edit | Only the fields sent change |
GET/POST /api/dashboard/admins, PATCH .../{id} |
admins.manage | Accounts; {name, role, active, password} |
GET /api/dashboard/roles |
signed in | The permission table and your role |
POST /api/dashboard/upload |
stays.edit | Multipart file (JPEG, PNG, WebP, 4 MB) → {url} |
Example: confirm and check in
curl -c jar -H "Content-Type: application/json" -d '{"email":"owner@nuzul.test","password":"..."}' http://localhost:3304/api/auth/login
curl -b jar -X PATCH -H "Content-Type: application/json" -d '{"status":"CONFIRMED"}' http://localhost:3304/api/dashboard/bookings/BOOKING_ID