Question types

A presentation holds up to 50 questions. Each question has a type; the fields below are checked when you save, and every problem is reported at once. Fields you leave out take their defaults.

Fields marked Secret (such as a quiz's correct answer) are kept out of the public view of a presentation and are never sent to phones before the answer is revealed.

Check a presentation without saving it with POST /v1/validate.

Presentation

Request body for creating or fully replacing a presentation (owner shape, including secret fields). Cross-field rules checked by the validator: question ids unique; serialized presentation at most 100 KiB.

Fields of presentation
Field	Type	Description
`title` required	string	Presentation title. 1–120 chars.
`settings`	Settings	Optional. Omitted fields take their defaults.
`questions` required	array of Question	1-50 questions in suggested slide order. Each id must be unique. 1–50 items.

{
  "title": "Q3 All-Hands",
  "settings": {
    "phone_display": "full",
    "leaderboard_size": 5,
    "show_rank_on_phone": true
  },
  "questions": [
    {
      "id": "warmup",
      "type": "word_cloud",
      "prompt": "One word for this quarter?"
    },
    {
      "id": "priority",
      "type": "poll",
      "prompt": "What should we focus on in Q4?",
      "options": [
        "Performance",
        "New features",
        "Onboarding",
        "Docs"
      ]
    },
    {
      "id": "launch_year",
      "type": "quiz",
      "prompt": "What year did we ship 1.0?",
      "options": [
        "2021",
        "2022",
        "2023",
        "2024"
      ],
      "correct": 1,
      "explanation": "Version 1.0 shipped in March 2022.",
      "time_limit_s": 20
    }
  ]
}

Settings

Presentation-level settings. Every field is optional and has a default.

Fields of settings
Field	Type	Description
`phone_display`	string	full: phones show the question text (and image) and options. answers_only: phones show only answer tiles (letter + shape + color, A-J); the room reads the question on the big screen. One of `full`, `answers_only`. Default `full`.
`leaderboard_size`	integer	Rows in the leaderboard shown on reveal of a scored question. 0 = no leaderboard. 0–20. Default `5`.
`show_rank_on_phone`	boolean	After reveal, each phone sees its own points and rank. Default `true`.
`accent_color`	string \| null	Join-page accent color as #RRGGBB, used for buttons, focus rings and the timer bar only (never answer tiles). null = default theme. Pattern `^#[0-9A-Fa-f]{6}$`. Default `null`.

{
  "phone_display": "answers_only",
  "leaderboard_size": 0,
  "show_rank_on_phone": false,
  "accent_color": "#1A2b3C"
}

`poll`

Multiple-choice vote with no correct answer. Cross-field rules checked by the validator: options unique (case-insensitive); max_choices only with multiple: true and at most the number of options.

Fields of poll
Field	Type	Description
`id` required	string	Author-chosen id, unique in the presentation. Pattern `^[a-z][a-z0-9_-]{0,31}$`.
`type` required	`poll`
`prompt` required	string	Question text. Plain text only. 1–300 chars.
`image_url`	string \| null	Optional https:// image shown on phones when phone_display is full. at most 2048 chars. Pattern `^https://`. Format uri. Default `null`.
`options` required	array of string	2-10 answer options, each 1-80 chars, unique. Option ids on the live connection are the lowercase letters a-j by index. 2–10 items.
`multiple`	boolean	Allow selecting more than one option. Default `false`.
`max_choices`	integer \| null	Only with multiple: true. Cap on selections, 2..number of options. null = no cap. At least 2. Default `null`.
`phone_results`	string	When phones see the vote distribution. One of `live`, `on_reveal`, `hidden`. Default `on_reveal`.
`time_limit_s`	integer \| null	Seconds open, 5-600. null = open until the deck moves on or reveals. 5–600. Default `null`.

{
  "id": "q-1",
  "type": "poll",
  "prompt": "Yes or no?",
  "options": [
    "Yes",
    "No"
  ],
  "max_choices": null,
  "time_limit_s": null,
  "image_url": null
}

`quiz`

Timed multiple choice with exactly one correct option; scored, leaderboard on reveal. Fields marked x-secret are never shown to participants before reveal. Cross-field rules checked by the validator: correct < number of options; options unique.

Fields of quiz
Field	Type	Description
`id` required	string	Author-chosen id, unique in the presentation. Pattern `^[a-z][a-z0-9_-]{0,31}$`.
`type` required	`quiz`
`prompt` required	string	Question text. Plain text only. 1–300 chars.
`image_url`	string \| null	Optional https:// image shown on phones when phone_display is full. at most 2048 chars. Pattern `^https://`. Format uri. Default `null`.
`options` required	array of string	2-6 answer options, each 1-80 chars, unique. Phones show them as colored shapes A-F. 2–6 items.
`correct` required	integer	0-based index into options of the one correct option (not the option text). 0–5. Secret: owner view only; never sent to phones before reveal.
`explanation`	string \| null	Optional explanation shown on the deck and phones at reveal. at most 300 chars. Default `null`. Secret: owner view only; never sent to phones before reveal.
`time_limit_s`	integer	Seconds open, 5-120. A quiz is always timed (scoring needs it). 5–120. Default `20`.
`points`	integer	Points for a correct answer. 0 = unscored knowledge check (no leaderboard contribution). 0–10000. Default `1000`.
`speed_bonus`	number	Extra fraction of points for an instant answer, decreasing linearly to 0 at the time limit. 0–1. Default `0.5`.

{
  "id": "launch_year",
  "type": "quiz",
  "prompt": "What year did we ship 1.0?",
  "options": [
    "2021",
    "2022",
    "2023",
    "2024"
  ],
  "correct": 1,
  "explanation": "Version 1.0 shipped in March 2022.",
  "time_limit_s": 20,
  "points": 1000,
  "speed_bonus": 0.5,
  "image_url": null
}

`word_cloud`

Short free-text answers aggregated into a word cloud. Not scored.

Fields of word_cloud
Field	Type	Description
`id` required	string	Author-chosen id, unique in the presentation. Pattern `^[a-z][a-z0-9_-]{0,31}$`.
`type` required	`word_cloud`
`prompt` required	string	Question text. Plain text only. 1–300 chars.
`image_url`	string \| null	Optional https:// image shown on phones when phone_display is full. at most 2048 chars. Pattern `^https://`. Format uri. Default `null`.
`max_entries`	integer	Entries per participant, 1-10, total across submissions. 1–10. Default `3`.
`max_length`	integer	Maximum characters per entry, 4-60. 4–60. Default `30`.
`phone_results`	string	When phones see the cloud. One of `live`, `on_reveal`, `hidden`. Default `live`.
`filter_profanity`	boolean	Silently drop entries matching the built-in profanity list. Default `true`.
`time_limit_s`	integer \| null	Seconds open, 5-600. null = open until the deck moves on or reveals. 5–600. Default `null`.

{
  "id": "cloud",
  "type": "word_cloud",
  "prompt": "What gives you energy?",
  "max_entries": 10,
  "max_length": 60,
  "phone_results": "hidden",
  "filter_profanity": false,
  "time_limit_s": 600
}