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

# Rooms and results

> Start a room, drive it the way the presenter's buttons do, and read every answer.

A **room** is one live session of a deck: a six-digit code, a QR, and the audience answering on their phones. The presenter drives it from the presenter view; an agent can drive it over the API with the same five actions.

## Start a room

```bash theme={null}
curl -X POST https://test.polltheroom.com/api/v1/rooms \
  -H "Authorization: Bearer ptr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deckId": "DECK_ID" }'
```

```json theme={null}
{
  "code": "491026",
  "hostToken": "c6f55304-…",
  "joinUrl": "https://test.polltheroom.com/j/491026",
  "presentUrl": "https://test.polltheroom.com/present/491026#host=c6f55304-…"
}
```

The room waits in the lobby. Hand `presentUrl` to the person presenting: it opens the presenter view and claims the host key from the fragment, so the person can take over from the agent at any point. `joinUrl` is what the audience opens.

<Warning>
  A deck with uploaded slide pages starts from the editor for now, because the pages are rendered in the browser. `start_room` answers `409` for such a deck and says so. Decks of blank slides and polls start here.
</Warning>

Starting rooms needs the `rooms:start` scope, which the Pro plan sells. The room needs every poll to pass [readiness](/concepts/readiness); otherwise `400` names the first problem.

## Drive it

`room_action` does what the presenter's buttons do, and answers with where the room is.

| Action  | Does                                                                                      |
| ------- | ----------------------------------------------------------------------------------------- |
| `start` | Begins the session at step 0.                                                             |
| `next`  | Locks whatever is live and walks to the next step. After the last step, the session ends. |
| `prev`  | Locks whatever is live and walks back.                                                    |
| `close` | Closes the live poll and reveals the result.                                              |
| `stop`  | Ends the session from anywhere.                                                           |

```bash theme={null}
curl -X POST https://test.polltheroom.com/api/v1/rooms/491026/actions \
  -H "Authorization: Bearer ptr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "next" }'
```

```json theme={null}
{ "status": "presenting", "stepIndex": 1, "stepCount": 5 }
```

An action that does not fit the room's state, `next` before `start` for example, answers `409` with a sentence.

## Read the results

`room_results` returns every poll's results so far, live or ended, as JSON and as a markdown summary ready to paste into a follow-up.

```bash theme={null}
curl https://test.polltheroom.com/api/v1/rooms/491026/results \
  -H "Authorization: Bearer ptr_YOUR_KEY"
```

```json theme={null}
{
  "code": "491026",
  "title": "Town hall",
  "status": "ended",
  "joined": 42,
  "pollCount": 4,
  "avgResponseRate": 0.81,
  "liveMinutes": 38,
  "polls": [ { "type": "multiple-choice", "prompt": "Which one?", "counts": { "…": 12 }, "totalAnswers": 34 } ],
  "markdown": "# Town hall\n\nRoom 491026. 42 joined. 4 polls. Live for 38 minutes.\n\n## Which one?\n…"
}
```

See [Read results](/guides/read-results) for what each widget puts in its snapshot.

<Note>
  Rooms live in memory on one server. Results are available while the room is held there, which is until the server restarts. Keeping them for good is on the roadmap.
</Note>

## List rooms

`list_rooms` returns the team's rooms, newest first, fifty at most, with each room's code, status and how many people joined.