Quickstart

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.

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 for scopes, plans and limits.

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.

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?" } }
    ]
  }'

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)

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"])

The answer:

{
  "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.

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.

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": [] } }'

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.

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.

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

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.

Get started

Concepts

Guides

Reference

Where next

Build a deck from a PDF

Give it to an agent

​Where next

Build a deck from a PDF

Give it to an agent

Where next