> ## 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.

# Decks and steps

> The document a deck is made of, and how the API changes it.

A deck is a JSON array of **steps**. It is the same shape the editor saves, and the API takes and returns it whole. There are three kinds of step.

<Tabs>
  <Tab title="Join screen">
    The opener: the six-digit code and the QR while the room fills. Always step 0, and there is only one.

    ```json theme={null}
    { "kind": "join" }
    ```
  </Tab>

  <Tab title="Slide">
    A page of the presenter's slides, or a blank, with things floating on it: up to four poll cards, eight text boxes, eight shapes and four images. Positions are fractions of the slide, 0 to 1.

    ```json theme={null}
    {
      "kind": "slide",
      "pageIndex": 3,
      "overlays": [
        {
          "poll": { "type": "multiple-choice", "prompt": "Which one?", "options": ["A", "B", "C"] },
          "rect": { "x": 0.6, "y": 0.52, "w": 0.36, "h": 0.42 }
        }
      ],
      "texts": [],
      "shapes": [],
      "images": [],
      "notes": "Ask the room before revealing."
    }
    ```

    `pageIndex` points at a page of the attached PDF; `null` is a blank slide.
  </Tab>

  <Tab title="Poll">
    One poll filling the screen.

    ```json theme={null}
    { "kind": "poll", "poll": { "type": "word-cloud", "prompt": "One word for today?" } }
    ```
  </Tab>
</Tabs>

## Cards

A poll on a slide is a **card**: the poll, a `rect` and a `style`. Leave both out and you get the house card, the bottom-right quarter with the default look, exactly what the editor drops. Send a partial `style` and only those fields change.

The card must stay on the slide: `x + w` and `y + h` at most 1. The API refuses a card that runs off. A card under a fifth of the slide's height is too small to read.

## Ids

Steps, cards, text boxes, shapes and images carry an `id`. Leave it out and the server fills one in. Ids survive `replace_step` for the steps you did not touch.

## Numbering

The API counts steps from 0, and 0 is the join screen. The editor's filmstrip shows the first slide as 1. So "slide 3" in the editor is step 3 in the API, since the join screen takes the 0.

## Changing a deck

Two ways, and both go through the same rules.

* **Whole document.** `update_deck` replaces the document as you send it. Never a merge.
* **One step at a time.** `add_step`, `replace_step`, `remove_step` and `add_overlay` change one step without resending the rest. They always write onto the revision they read.

Every write answers with `revision`, `ready` and `problems`. See [Readiness](/concepts/readiness) and [Revisions](/authentication#revisions).

## The widgets

Every poll has a `type`, a `prompt` and, where it takes answers, `options`. The seventeen widgets, the properties each reads, the looks it can take and what it needs before it can go on stage are all in the [document and widgets reference](/reference/document-and-widgets), generated from the code that enforces them.