# Rooms

Rooms represent physical dining areas within a table layout. Each room can contain multiple tables arranged on a 2D canvas. Rooms are used by the POS and reception interfaces to visually manage seating and table assignments.

**Access flag required:** Creating, updating, and deleting rooms requires the `CAN_EDIT_TABLE_LAYOUT` access flag in addition to role-based authorization.

**Polling on `updatedAt`:** creating, updating or deleting a room now moves the `updatedAt` of the table layout that contains it, and updating a room also moves the room's own `updatedAt`, even when only its tables changed. Tables are stored as their own records, so both timestamps previously stayed frozen when a table was moved, added or removed, and an integration diffing them saw no change. An `updatedAt` that moved forward is now a reliable signal to re-read the floor plan.

### `GET /rooms/{roomUuid}` - Get Room

Retrieve a specific room by its UUID, including its list of tables with their positions and dimensions.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| roomUuid | string (UUID) | Yes | The UUID of the room. |

#### Response

```json
{
  "status": 200,
  "code": "room_succeed",
  "message": "Room was successfully found.",
  "data": {
    "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Main Dining Hall",
    "tableLayoutId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
    "position": 0,
    "tables": [
      {
        "tableId": "11112222-3333-4444-5555-666677778888",
        "name": "T1",
        "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "positionX": 100,
        "positionY": 200,
        "height": 80,
        "width": 80
      },
      {
        "tableId": "99998888-7777-6666-5555-444433332222",
        "name": "T2",
        "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "positionX": 300,
        "positionY": 200,
        "height": 80,
        "width": 120
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "room\_succeed" | Machine-readable application code for the result. |
| message | string | "Room was successfully found." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.roomId | string | "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | Identifier of the associated room. |
| data.name | string | "Main Dining Hall" | The name value. |
| data.tableLayoutId | string | "f0e1d2c3-b4a5-6789-0fed-cba987654321" | Identifier of the associated table layout. |
| data.position | integer | 0 | The position value. |
| data.tables | array | \[…\] | List of tables entries. |
| data.tables\[\] | object | {…} | Object containing tables fields. |
| data.tables\[\].tableId | string | "11112222-3333-4444-5555-666677778888" | Identifier of the associated table. |
| data.tables\[\].name | string | "T1" | The name value. |
| data.tables\[\].roomId | string | "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | Identifier of the associated room. |
| data.tables\[\].positionX | integer | 100 | The position x value. |
| data.tables\[\].positionY | integer | 200 | The position y value. |
| data.tables\[\].height | integer | 80 | The height value. |
| data.tables\[\].width | integer | 80 | The width value. |

### `POST /rooms` - Create Room

Create a new room within a table layout, optionally including an initial set of tables. Each table requires a name and 2D positioning (positionX, positionY, height, width).

#### Request Body

```json
{
  "name": "Terrace",
  "tableLayoutId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
  "position": 1,
  "tables": [
    {
      "name": "T10",
      "positionX": 50,
      "positionY": 50,
      "height": 80,
      "width": 80
    },
    {
      "name": "T11",
      "positionX": 200,
      "positionY": 50,
      "height": 80,
      "width": 80
    }
  ]
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| name | string | "Terrace" | The name value. |
| tableLayoutId | string | "f0e1d2c3-b4a5-6789-0fed-cba987654321" | Identifier of the associated table layout. |
| position | integer | 1 | The position value. |
| tables | array | \[…\] | List of tables entries. |
| tables\[\] | object | {…} | Object containing tables fields. |
| tables\[\].name | string | "T10" | The name value. |
| tables\[\].positionX | integer | 50 | The position x value. |
| tables\[\].positionY | integer | 50 | The position y value. |
| tables\[\].height | integer | 80 | The height value. |
| tables\[\].width | integer | 80 | The width value. |

#### Response

```json
{
  "status": 200,
  "code": "room_created",
  "message": "Room was successfully created.",
  "data": {
    "roomId": "dd445566-7788-99aa-bbcc-ddeeff001122",
    "name": "Terrace",
    "tableLayoutId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
    "position": 1,
    "tables": [
      {
        "tableId": "aabb1122-3344-5566-7788-99aabbccddee",
        "name": "T10",
        "positionX": 50,
        "positionY": 50,
        "height": 80,
        "width": 80
      },
      {
        "tableId": "ffeeddcc-bbaa-9988-7766-554433221100",
        "name": "T11",
        "positionX": 200,
        "positionY": 50,
        "height": 80,
        "width": 80
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "room\_created" | Machine-readable application code for the result. |
| message | string | "Room was successfully created." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.roomId | string | "dd445566-7788-99aa-bbcc-ddeeff001122" | Identifier of the associated room. |
| data.name | string | "Terrace" | The name value. |
| data.tableLayoutId | string | "f0e1d2c3-b4a5-6789-0fed-cba987654321" | Identifier of the associated table layout. |
| data.position | integer | 1 | The position value. |
| data.tables | array | \[…\] | List of tables entries. |
| data.tables\[\] | object | {…} | Object containing tables fields. |
| data.tables\[\].tableId | string | "aabb1122-3344-5566-7788-99aabbccddee" | Identifier of the associated table. |
| data.tables\[\].name | string | "T10" | The name value. |
| data.tables\[\].positionX | integer | 50 | The position x value. |
| data.tables\[\].positionY | integer | 50 | The position y value. |
| data.tables\[\].height | integer | 80 | The height value. |
| data.tables\[\].width | integer | 80 | The width value. |

### `PUT /rooms/{roomUuid}` - Update Room

Update a room and its tables. Provide the full list of tables in the room; tables not included will be removed, new entries will be created, and existing ones will be updated.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| roomUuid | string (UUID) | Yes | The UUID of the room to update. |

#### Request Body

```json
{
  "name": "Main Dining Hall (Updated)",
  "tables": [
    {
      "tableId": "11112222-3333-4444-5555-666677778888",
      "name": "T1",
      "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "positionX": 120,
      "positionY": 220,
      "height": 80,
      "width": 80
    },
    {
      "name": "T3",
      "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "positionX": 500,
      "positionY": 200,
      "height": 100,
      "width": 100
    }
  ]
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| name | string | "Main Dining Hall (Updated)" | The name value. |
| tables | array | \[…\] | List of tables entries. |
| tables\[\] | object | {…} | Object containing tables fields. |
| tables\[\].tableId | string | "11112222-3333-4444-5555-666677778888" | Identifier of the associated table. |
| tables\[\].name | string | "T1" | The name value. |
| tables\[\].roomId | string | "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | Identifier of the associated room. |
| tables\[\].positionX | integer | 120 | The position x value. |
| tables\[\].positionY | integer | 220 | The position y value. |
| tables\[\].height | integer | 80 | The height value. |
| tables\[\].width | integer | 80 | The width value. |

#### Response

```json
{
  "status": 200,
  "code": "room_updated",
  "message": "Room was successfully updated.",
  "data": {
    "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Main Dining Hall (Updated)",
    "tables": [
      {
        "tableId": "11112222-3333-4444-5555-666677778888",
        "name": "T1",
        "positionX": 120,
        "positionY": 220,
        "height": 80,
        "width": 80
      },
      {
        "tableId": "cc112233-4455-6677-8899-aabbccddeeff",
        "name": "T3",
        "positionX": 500,
        "positionY": 200,
        "height": 100,
        "width": 100
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "room\_updated" | Machine-readable application code for the result. |
| message | string | "Room was successfully updated." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.roomId | string | "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | Identifier of the associated room. |
| data.name | string | "Main Dining Hall (Updated)" | The name value. |
| data.tables | array | \[…\] | List of tables entries. |
| data.tables\[\] | object | {…} | Object containing tables fields. |
| data.tables\[\].tableId | string | "11112222-3333-4444-5555-666677778888" | Identifier of the associated table. |
| data.tables\[\].name | string | "T1" | The name value. |
| data.tables\[\].positionX | integer | 120 | The position x value. |
| data.tables\[\].positionY | integer | 220 | The position y value. |
| data.tables\[\].height | integer | 80 | The height value. |
| data.tables\[\].width | integer | 80 | The width value. |

### `DELETE /rooms/{roomUuid}` - Delete Room

Delete a room and all its associated tables. This action is irreversible.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| roomUuid | string (UUID) | Yes | The UUID of the room to delete. |

#### Response

```json
{
  "status": 200,
  "code": "room_deleted",
  "message": "Room was successfully deleted.",
  "data": {}
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "room\_deleted" | Machine-readable application code for the result. |
| message | string | "Room was successfully deleted." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |