> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rooms

> Create, list, retrieve, and update rooms. Supports CRM linking, templates, and duplication.

## Endpoints

| Method  | Path                      | Description   |
| ------- | ------------------------- | ------------- |
| `POST`  | `/api/v2/rooms`           | Create a room |
| `GET`   | `/api/v2/rooms/{room_id}` | Get a room    |
| `GET`   | `/api/v2/rooms`           | List rooms    |
| `PATCH` | `/api/v2/rooms/{room_id}` | Update a room |

***

## Create a room

`POST /api/v2/rooms`

### Body parameters

<ParamField body="title" type="string">
  The display title of the room.
</ParamField>

<ParamField body="description" type="string">
  Optional description.
</ParamField>

<ParamField body="templateId" type="string">
  Template ID to initialise the room from. Ignored when `duplicateFromId` is set.
</ParamField>

<ParamField body="duplicateFromId" type="string">
  ID of an existing room to duplicate.
</ParamField>

<ParamField body="companyId" type="string">
  ID of the company to associate with this room.
</ParamField>

<ParamField body="statusId" type="string">
  ID of the status to set on the room.
</ParamField>

<ParamField body="labelId" type="string">
  ID of the label to apply.
</ParamField>

<ParamField body="userId" type="string">
  ID of the Flowla user to assign as room owner.
</ParamField>

<ParamField body="email" type="string">
  Email address of the primary contact.
</ParamField>

<ParamField body="hsDealId" type="string">
  HubSpot deal ID to link this room to.
</ParamField>

<ParamField body="sfOpportunityId" type="string">
  Salesforce opportunity ID (e.g. `0064x000009abcD`).
</ParamField>

<ParamField body="attioDealId" type="string">
  Attio deal ID (e.g. `deal-abc-123`).
</ParamField>

<ParamField body="coverTitle" type="string">
  Title displayed on the room's cover page.
</ParamField>

<ParamField body="coverDescription" type="string">
  Description displayed on the room's cover page.
</ParamField>

<ParamField body="coverDisabled" type="boolean">
  When `true`, the cover page is hidden.
</ParamField>

<ParamField body="themeColor" type="string">
  Background color as a hex value (e.g. `#FF5500`).
</ParamField>

<ParamField body="navColor" type="string">
  Navigation bar color. Accepts a hex value, `"flow-org-color"` (your org's brand color), or `"target-company-color"` (the associated company's color).
</ParamField>

### Modes

<Tabs>
  <Tab title="Blank room">
    ```json theme={null}
    {
      "title": "Acme Corp – Onboarding",
      "email": "buyer@acme.com",
      "companyId": "<company_id>"
    }
    ```
  </Tab>

  <Tab title="From template">
    ```json theme={null}
    {
      "title": "Acme Corp – Onboarding",
      "templateId": "<template_id>",
      "email": "buyer@acme.com"
    }
    ```
  </Tab>

  <Tab title="Duplicate room">
    ```json theme={null}
    {
      "title": "Acme Corp – Onboarding (copy)",
      "duplicateFromId": "<room_id>"
    }
    ```
  </Tab>

  <Tab title="With CRM link">
    ```json theme={null}
    {
      "title": "Globex Q3 Deal",
      "templateId": "<template_id>",
      "hsDealId": "12345678",
      "userId": "<user_id>"
    }
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.flowla.com/api/v2/rooms \
    -H "x-flowla-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Acme Corp – Onboarding",
      "templateId": "<template_id>",
      "email": "buyer@acme.com",
      "hsDealId": "12345678"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.flowla.com/api/v2/rooms",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      json={
          "title": "Acme Corp – Onboarding",
          "templateId": "<template_id>",
          "email": "buyer@acme.com",
          "hsDealId": "12345678",
      },
  )
  print(response.json())
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.flowla.com/api/v2/rooms", {
    method: "POST",
    headers: {
      "x-flowla-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Acme Corp – Onboarding",
      templateId: "<template_id>",
      email: "buyer@acme.com",
      hsDealId: "12345678",
    }),
  });
  const room = await res.json();
  ```
</CodeGroup>

***

## Get a room

`GET /api/v2/rooms/{room_id}`

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flowla.com/api/v2/rooms/<room_id> \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.flowla.com/api/v2/rooms/<room_id>",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
  )
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.flowla.com/api/v2/rooms/<room_id>", {
    headers: { "x-flowla-api-key": "YOUR_API_KEY" },
  });
  ```
</CodeGroup>

***

## List rooms

`GET /api/v2/rooms`

### Query parameters

<ParamField query="page" type="number">
  Page number (default: 1).
</ParamField>

<ParamField query="limit" type="number">
  Results per page (default: 10).
</ParamField>

<ParamField query="sortBy" type="&#x22;createdAt&#x22; | &#x22;updatedAt&#x22; | &#x22;totalEngagements&#x22; | &#x22;lastEngagedAt&#x22;">
  Field to sort by (default: `createdAt`).
</ParamField>

<ParamField query="sortDirection" type="&#x22;ASC&#x22; | &#x22;DESC&#x22;">
  Sort direction (default: `DESC`).
</ParamField>

### Response fields

Each room in `results` includes:

| Field              | Type            | Description                                                                                    |
| ------------------ | --------------- | ---------------------------------------------------------------------------------------------- |
| `id`               | string          | Room identifier                                                                                |
| `title`            | string          | Room title                                                                                     |
| `userId`           | string \| null  | Room owner user ID                                                                             |
| `companyId`        | string \| null  | Associated company ID                                                                          |
| `createdAt`        | string          | ISO 8601                                                                                       |
| `updatedAt`        | string          | ISO 8601                                                                                       |
| `totalEngagements` | number \| null  | Total engagement actions across all types                                                      |
| `lastEngagedAt`    | string \| null  | Timestamp of the last engagement                                                               |
| `totalViews`       | number \| null  | Total page view count                                                                          |
| `totalUniqueViews` | number \| null  | Unique viewer count                                                                            |
| `engagements`      | object \| null  | Breakdown: `clicks`, `comments`, `downloads`, `reactions`, `shares`, `views`, `tasksCompleted` |
| `coverTitle`       | string \| null  | Cover page title                                                                               |
| `coverDescription` | string \| null  | Cover page description                                                                         |
| `coverDisabled`    | boolean \| null | Whether the cover page is hidden                                                               |
| `themeColor`       | string \| null  | Background color                                                                               |
| `navColor`         | string \| null  | Navigation bar color                                                                           |

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.flowla.com/api/v2/rooms?page=1&limit=20" \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.flowla.com/api/v2/rooms",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      params={"page": 1, "limit": 20},
  )
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.flowla.com/api/v2/rooms?page=1&limit=20", {
    headers: { "x-flowla-api-key": "YOUR_API_KEY" },
  });
  ```
</CodeGroup>

***

## Update a room

`PATCH /api/v2/rooms/{room_id}`

All fields are optional. Only provided fields are updated.

<ParamField body="title" type="string">
  New display title.
</ParamField>

<ParamField body="description" type="string">
  New description.
</ParamField>

<ParamField body="statusId" type="string">
  New status ID.
</ParamField>

<ParamField body="userId" type="string">
  Sets the room owner.
</ParamField>

<ParamField body="companyId" type="string">
  Links the room to a company.
</ParamField>

<ParamField body="hsDealId" type="string">
  HubSpot deal ID.
</ParamField>

<ParamField body="sfOpportunityId" type="string">
  Salesforce opportunity ID.
</ParamField>

<ParamField body="attioDealId" type="string">
  Attio deal ID.
</ParamField>

<ParamField body="coverTitle" type="string">
  Cover page title.
</ParamField>

<ParamField body="coverDescription" type="string">
  Cover page description.
</ParamField>

<ParamField body="coverDisabled" type="boolean">
  When `true`, the cover page is hidden.
</ParamField>

<ParamField body="themeColor" type="string">
  Background color as a hex value (e.g. `#FF5500`).
</ParamField>

<ParamField body="navColor" type="string">
  Navigation bar color. Accepts a hex value, `"flow-org-color"`, or `"target-company-color"`.
</ParamField>

```json Example theme={null}
{
  "title": "Globex – Closed Won",
  "statusId": "<status_id>",
  "userId": "<user_id>"
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.flowla.com/api/v2/rooms/<room_id> \
    -H "x-flowla-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"title": "Globex – Closed Won", "statusId": "<status_id>"}'
  ```

  ```python Python theme={null}
  requests.patch(
      "https://api.flowla.com/api/v2/rooms/<room_id>",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      json={"title": "Globex – Closed Won", "statusId": "<status_id>"},
  )
  ```

  ```js JavaScript theme={null}
  await fetch("https://api.flowla.com/api/v2/rooms/<room_id>", {
    method: "PATCH",
    headers: {
      "x-flowla-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ title: "Globex – Closed Won", statusId: "<status_id>" }),
  });
  ```
</CodeGroup>