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

# Rooms API

> List, view and create rooms in your Zapnito community through the API, with pagination and example requests.

Get details of the rooms in your community, and create new ones.

Before you start, read the [API overview](/api/v1/overview) for how authentication, headers, pagination and errors work.

## List rooms

Return the rooms in your community.

<ParamField query="page" type="integer">
  The page of results to return.
</ParamField>

<ParamField query="per_page" type="integer">
  The number of results to return per page.
</ParamField>

<ParamField query="query" type="string">
  A search term to reduce the number of results. Matches name.
</ParamField>

```bash title="List rooms" theme={null}
curl "https://your-community.zapnito.com/api/v1/rooms?page=1&per_page=20" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

`GET https://your-community.zapnito.com/api/v1/rooms`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "rooms": [
      {
        "name": "Audit Readiness",
        "description": "Prepare for audits with checklists, templates and expert advice",
        "about": "Checklists, templates and advice from members who have been through an audit.",
        "position": 1,
        "type": "public",
        "contributor_group_uuid": "52218d7c-ff20-4abd-b674-d377d8a8e0ba",
        "member_group_uuid": "52218d7c-ff20-4abd-b674-d377d8a8e0bv"
      },
      {
        "name": "Compliance Practice",
        "description": "Share practical advice on day-to-day compliance work",
        "about": "A space for compliance professionals to compare approaches and ask questions.",
        "position": 2,
        "type": "public",
        "contributor_group_uuid": "52218d7c-ff20-4abd-b674-d377d8a8e0ba",
        "member_group_uuid": "52218d7c-ff20-4abd-b674-d377d8a8e0bv"
      }
    ]
  }
  ```
</ResponseExample>

## Get a room

Return a single room.

<ParamField path="room_id" type="string" required>
  The ID of the room.
</ParamField>

```bash title="Get a room" theme={null}
curl "https://your-community.zapnito.com/api/v1/rooms/123" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

`GET https://your-community.zapnito.com/api/v1/rooms/:room_id`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "room": {
      "name": "Audit Readiness",
      "description": "Prepare for audits with checklists, templates and expert advice",
      "about": "Checklists, templates and advice from members who have been through an audit.",
      "position": 1,
      "type": "public",
      "contributor_group_uuid": "52218d7c-ff20-4abd-b674-d377d8a8e0ba",
      "member_group_uuid": "52218d7c-ff20-4abd-b674-d377d8a8e0bv"
    }
  }
  ```
</ResponseExample>

* `200 OK`: the room was returned.
* `404 Not Found`: no room matches the ID.

## Create a room

Create a new room.

<ParamField body="room.name" type="string" required>
  The name of the room.
</ParamField>

<ParamField body="room.description" type="string" required>
  The description of the room.
</ParamField>

<ParamField body="room.about" type="string">
  The about text of the room.
</ParamField>

<ParamField body="room.position" type="integer">
  The position of the room in your room list.
</ParamField>

<ParamField body="room.owner_email" type="string" required>
  The email address of the room's owner, who becomes the initial contributor. This is usually your own email address, and the user must be able to create rooms.
</ParamField>

<ParamField body="room.type" type="string" default="public">
  The type of room. Accepts `public`, `private` or `secret`.
</ParamField>

```bash title="Create a room" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/rooms" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "room": {
      "name": "Audit Readiness",
      "description": "Prepare for audits with checklists, templates and expert advice",
      "about": "Checklists, templates and advice from members who have been through an audit.",
      "position": 1,
      "owner_email": "sam.jones@example.com"
    }
  }'
```

`POST https://your-community.zapnito.com/api/v1/rooms`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "room": {
      "id": 123,
      "name": "Audit Readiness",
      "description": "Prepare for audits with checklists, templates and expert advice",
      "about": "Checklists, templates and advice from members who have been through an audit.",
      "position": 1,
      "contributor_group_uuid": "a1ecad96-8849-45ba-821e-20199cde45cd",
      "member_group_uuid": "a1ecad96-8849-45ba-821e-20199cde45cd"
    }
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "errors": {
      "description": ["can't be blank"],
      "name": ["has already been taken"]
    }
  }
  ```
</ResponseExample>

* `200 OK`: the room was created.
* `422 Unprocessable Entity`: a required parameter is missing or taken, or no user matches `owner_email`. In the second case the response is `{"errors": {"owner_email": ["Couldn't find User"]}}`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.