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

# Build a deck from a PDF

> Attach the presenter's slides, put a poll on the right pages, and look at what you made.

This is the path an agent takes when a presenter hands it a slide deck. Five requests, and the presenter opens the result in the editor.

<Steps>
  <Step title="Create the deck">
    A title is enough. The deck opens with the join screen and one blank slide.

    ```bash theme={null}
    curl -X POST https://test.polltheroom.com/api/v1/decks \
      -H "Authorization: Bearer ptr_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "title": "Analytic budgeting" }'
    ```
  </Step>

  <Step title="Attach the PDF">
    Send the file as base64 in `pdf`, with `pages` set to the page count. While no slide has a page yet, the blank slides are replaced by one slide per page, in order, after the join screen. Polls already in the deck are kept.

    ```bash theme={null}
    PDF=$(base64 -i slides.pdf)
    curl -X PUT https://test.polltheroom.com/api/v1/decks/DECK_ID/source \
      -H "Authorization: Bearer ptr_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d "{ \"pdf\": \"$PDF\", \"pages\": 7 }"
    ```

    ```json theme={null}
    { "ok": true, "slides": 7, "revision": "…", "ready": true, "problems": [] }
    ```

    PDF only for now, 24 MB at most, 60 pages at most. The editor renders the pages when the deck is opened.
  </Step>

  <Step title="Decide where a poll helps">
    Read the PDF yourself. Not every slide deserves a poll; three to five in a deck of ten to twenty slides is the usual rhythm. Good moments: a claim the room can vote on, a number to estimate before it is revealed, a choice between two directions, a word cloud at the end.
  </Step>

  <Step title="Put each poll on its slide">
    `add_overlay` drops a card on one slide. Leave `rect` and `style` out for the house card in the bottom-right quarter. When that corner holds text on the slide, give a `rect` that covers a picture or empty space instead. Never cover text.

    ```bash theme={null}
    curl -X POST https://test.polltheroom.com/api/v1/decks/DECK_ID/steps/4/overlays \
      -H "Authorization: Bearer ptr_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "poll": { "type": "this-or-that", "prompt": "Top-down or bottom-up?", "options": ["Top-down", "Bottom-up"] },
        "rect": { "x": 0.05, "y": 0.55, "w": 0.4, "h": 0.4 }
      }'
    ```

    Step 4 is the fourth page, since step 0 is the join screen. A full-screen question goes in with `add_step` instead.
  </Step>

  <Step title="Look at every slide you touched">
    `get_screenshot` returns the slide as the editor shows it. Check that the card sits on a picture or empty space and is large enough to read; move it if not.

    ```bash theme={null}
    curl https://test.polltheroom.com/api/v1/decks/DECK_ID/steps/4/screenshot \
      -H "Authorization: Bearer ptr_YOUR_KEY" -H "Accept: image/png" -o step-4.png
    ```
  </Step>

  <Step title="Hand it over">
    Read the deck once more and make sure `ready` is true. Then give the presenter the editor `url` from the first step. They open it, the pages render, and they press Present.
  </Step>
</Steps>

## The same flow over MCP

With the [MCP server](/mcp) connected, the tools are `create_deck`, `attach_pdf`, `add_overlay`, `get_screenshot` and `get_deck`, and the screenshot comes back as an image the agent can see. The server's instructions tell the agent this flow on connect.