Rooms API

Manage rooms within an organization — create, list, retrieve, update availability, and delete.

Authentication

All endpoints require a valid Bearer token in the Authorization header.

Endpoints

Method	Path	Description
POST	/api/rooms/:orgId/create	Create a new room
GET	/api/rooms/:orgId/list	List all rooms
GET	/api/rooms/:orgId/overview	Get rooms overview / stats
GET	/api/rooms/:orgId/by-number/:roomNo	Get room by room number
GET	/api/rooms/:orgId/:roomId	Get room by ID
PUT	/api/rooms/:orgId/:roomId/available	Toggle room availability
PUT	/api/rooms/:orgId/:roomId/update	Update room details
DELETE	/api/rooms/:orgId/:roomId/delete	Delete a room

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
roomId	string	Room document ID
roomNo	string	Room number (e.g. 101, A-201)

---

Create Room

POST /api/rooms/:orgId/create

Request Body

{
  "roomNumber": "301",
  "categoryId": "64f1b2c3d4e5f6a7b8c9d0e1",
  "floor": 3,
  "description": "Ocean-view deluxe room with balcony",
  "amenities": ["wifi", "minibar", "balcony", "air-conditioning"],
  "maxOccupancy": 3,
  "basePrice": 7500,
  "isAvailable": true
}

Success Response 201

{
  "success": true,
  "message": "Room created successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e2",
    "roomNumber": "301",
    "categoryId": {
      "_id": "64f1b2c3d4e5f6a7b8c9d0e1",
      "name": "Deluxe Suite"
    },
    "floor": 3,
    "description": "Ocean-view deluxe room with balcony",
    "amenities": ["wifi", "minibar", "balcony", "air-conditioning"],
    "maxOccupancy": 3,
    "basePrice": 7500,
    "isAvailable": true,
    "orgId": "64f1b2c3d4e5f6a7b8c9d0e0",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
}

Error Response 400

{
  "success": false,
  "message": "Validation error",
  "errors": [
    "roomNumber is required",
    "categoryId is required"
  ]
}

Error Response 409

{
  "success": false,
  "message": "Room with number 301 already exists"
}

---

List Rooms

GET /api/rooms/:orgId/list

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Results per page
search	string	—	Search by room number or description
categoryId	string	—	Filter by room category
floor	number	—	Filter by floor number
available	boolean	—	Filter by availability (true/false)

Success Response 200

{
  "success": true,
  "data": [
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0e2",
      "roomNumber": "301",
      "categoryId": {
        "_id": "64f1b2c3d4e5f6a7b8c9d0e1",
        "name": "Deluxe Suite"
      },
      "floor": 3,
      "maxOccupancy": 3,
      "basePrice": 7500,
      "isAvailable": true
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

---

Rooms Overview

GET /api/rooms/:orgId/overview

Returns aggregate statistics about the room inventory.

Success Response 200

{
  "success": true,
  "data": {
    "totalRooms": 50,
    "available": 32,
    "occupied": 15,
    "underMaintenance": 3,
    "byCategory": [
      { "category": "Deluxe Suite", "count": 15 },
      { "category": "Standard", "count": 20 },
      { "category": "Premium", "count": 15 }
    ],
    "byFloor": [
      { "floor": 1, "count": 12 },
      { "floor": 2, "count": 14 },
      { "floor": 3, "count": 12 },
      { "floor": 4, "count": 12 }
    ]
  }
}

---

Get Room by Number

GET /api/rooms/:orgId/by-number/:roomNo

Success Response 200

{
  "success": true,
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e2",
    "roomNumber": "301",
    "categoryId": {
      "_id": "64f1b2c3d4e5f6a7b8c9d0e1",
      "name": "Deluxe Suite"
    },
    "floor": 3,
    "description": "Ocean-view deluxe room with balcony",
    "amenities": ["wifi", "minibar", "balcony", "air-conditioning"],
    "maxOccupancy": 3,
    "basePrice": 7500,
    "isAvailable": true,
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Room not found"
}

---

Get Room by ID

GET /api/rooms/:orgId/:roomId

Success Response 200

Same structure as Get Room by Number.

Error Response 404

{
  "success": false,
  "message": "Room not found"
}

---

Toggle Room Availability

PUT /api/rooms/:orgId/:roomId/available

Request Body

{
  "isAvailable": false,
  "reason": "Under maintenance"
}

Success Response 200

{
  "success": true,
  "message": "Room availability updated",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e2",
    "roomNumber": "301",
    "isAvailable": false,
    "updatedAt": "2026-02-21T08:30:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Room not found"
}

---

Update Room

PUT /api/rooms/:orgId/:roomId/update

Request Body

{
  "description": "Renovated ocean-view deluxe room with private balcony",
  "amenities": ["wifi", "minibar", "balcony", "air-conditioning", "smart-tv"],
  "maxOccupancy": 4,
  "basePrice": 8500
}

Success Response 200

{
  "success": true,
  "message": "Room updated successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e2",
    "roomNumber": "301",
    "description": "Renovated ocean-view deluxe room with private balcony",
    "amenities": ["wifi", "minibar", "balcony", "air-conditioning", "smart-tv"],
    "maxOccupancy": 4,
    "basePrice": 8500,
    "updatedAt": "2026-02-21T09:00:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Room not found"
}

---

Delete Room

DELETE /api/rooms/:orgId/:roomId/delete

Success Response 200

{
  "success": true,
  "message": "Room deleted successfully"
}

Error Response 404

{
  "success": false,
  "message": "Room not found"
}

Error Response 409

{
  "success": false,
  "message": "Cannot delete room with active bookings"
}