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

# Quickstart

> A key, one request, and a deck you can open in the editor.

<Note>
  The API runs on `https://test.polltheroom.com` until launch. Every example below uses that host; nothing else changes when the root domain goes live.
</Note>

<Steps>
  <Step title="Make a key">
    Sign in and open **Settings › API**. Give the key a name and the scopes it needs. The secret is shown once and starts with `ptr_`; only a hash is stored, so copy it now.

    A key belongs to your team. On the free plan it may read and write decks; starting rooms over the API is a Pro feature. See [Authentication](/authentication) for scopes, plans and limits.
  </Step>

  <Step title="Create a deck">
    Send the key as a bearer token. This makes a deck with the join screen and one word cloud, and answers with its id and where to open it.

    <CodeGroup>
      ```bash curl 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": "First deck",
          "document": [
            { "kind": "join" },
            { "kind": "poll", "poll": { "type": "word-cloud", "prompt": "One word for today?" } }
          ]
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://test.polltheroom.com/api/v1/decks", {
        method: "POST",
        headers: {
          Authorization: "Bearer ptr_YOUR_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          title: "First deck",
          document: [
            { kind: "join" },
            { kind: "poll", poll: { type: "word-cloud", prompt: "One word for today?" } },
          ],
        }),
      })
      const deck = await response.json()
      console.log(deck.url)
      ```

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

      response = requests.post(
          "https://test.polltheroom.com/api/v1/decks",
          headers={"Authorization": "Bearer ptr_YOUR_KEY"},
          json={
              "title": "First deck",
              "document": [
                  {"kind": "join"},
                  {"kind": "poll", "poll": {"type": "word-cloud", "prompt": "One word for today?"}},
              ],
          },
      )
      print(response.json()["url"])
      ```
    </CodeGroup>

    The answer:

    ```json theme={null}
    {
      "id": "cmtr9ym820007uq2m42hqimq2",
      "url": "https://test.polltheroom.com/new?doc=cmtr9ym820007uq2m42hqimq2",
      "revision": "2026-09-07T13:26:56.407Z",
      "ready": true,
      "problems": []
    }
    ```

    Ids on steps and cards are filled in when you leave them out. `ready` and `problems` are the readiness check, run for you on every write.
  </Step>

  <Step title="Put a poll on a slide">
    Add a blank slide, then drop a rating on it. Leave `rect` and `style` out and the card gets the house look in the bottom-right quarter, exactly as when a person drops a widget in the editor.

    ```bash theme={null}
    curl -X POST https://test.polltheroom.com/api/v1/decks/DECK_ID/steps \
      -H "Authorization: Bearer ptr_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "step": { "kind": "slide", "pageIndex": null, "overlays": [] } }'
    ```

    ```bash theme={null}
    curl -X POST https://test.polltheroom.com/api/v1/decks/DECK_ID/steps/2/overlays \
      -H "Authorization: Bearer ptr_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "poll": { "type": "rating", "prompt": "How was this session?" } }'
    ```

    Step 0 is the join screen and stays put; the word cloud is step 1; the new slide is step 2.
  </Step>

  <Step title="Look at it">
    Ask for a screenshot of the slide, as the editor shows it. With `Accept: image/png` you get the bytes; without it, JSON with the image as a data URL.

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

  <Step title="Open it in the editor">
    The `url` from step 2 opens the deck in the editor for a signed-in presenter. Press **Present** there, and the room is live with a six-digit code and a QR.
  </Step>
</Steps>

## Where next

<CardGroup cols={2}>
  <Card title="Build a deck from a PDF" icon="file-pdf" href="/guides/build-a-deck-from-a-pdf">
    Attach the presenter's slides and put polls on the right pages.
  </Card>

  <Card title="Give it to an agent" icon="plug" href="/mcp">
    Connect the MCP server to Claude Code, Cursor or Codex in one command.
  </Card>
</CardGroup>