For: Full Stack · Backend API

API reference

Every endpoint of the Nuzul API, with its permissions and answers.

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