> ## 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. # Add a step > Append a slide or a poll step, or insert it before a given index, without resending the document. The join screen is step 0 and there is only one. Needs the `decks:write` scope. ## OpenAPI ````yaml https://test.polltheroom.com/openapi.json post /api/v1/decks/{id}/steps openapi: 3.1.0 info: title: Poll the Room API version: '1' description: >- Live polls on a presenter's own slides. A presenter (or an agent acting for one) builds a deck; the audience joins on their phones with a six-digit code and never signs up. Keys are made under Settings › API and sent as `Authorization: Bearer ptr_…`. A key belongs to a team, carries scopes, and is rate limited per hour. Plans: Free may decks:read, decks:write, rooms:read, results:read at 60 requests an hour; Pro may decks:read, decks:write, rooms:read, rooms:start, results:read at 1000 requests an hour. The same verbs are MCP tools at https://test.polltheroom.com/api/mcp. The full reference is at https://test.polltheroom.com/llms-full.txt. servers: - url: https://test.polltheroom.com security: - apiKey: [] tags: - name: decks description: A deck is a document the editor and the API both read and write. - name: rooms description: A room is one live session of a deck. paths: /api/v1/decks/{id}/steps: post: tags: - decks summary: Add a step description: >- Append a slide or a poll step, or insert it before a given index, without resending the document. The join screen is step 0 and there is only one. Needs the `decks:write` scope. operationId: add_step parameters: - name: id in: path required: true schema: type: string minLength: 1 description: The deck's id requestBody: required: true content: application/json: schema: type: object properties: step: oneOf: - type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 kind: type: string const: join required: - kind description: >- The mandatory opener: the code and QR while the room fills. Always first. - type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 kind: type: string const: slide pageIndex: anyOf: - type: integer minimum: 0 maximum: 199 - type: 'null' description: >- The uploaded page behind the slide; null is a blank slide overlays: maxItems: 4 type: array items: type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 poll: type: object properties: type: type: string enum: - multiple-choice - image-choice - this-or-that - ranking - hundred-points - rating - nps - estimate - radar - word-cloud - open-feed - qa-upvotes - timer - wheel - map - place-map - rounds prompt: type: string maxLength: 140 description: The question, as it reads on screen timeLimitSec: default: null anyOf: - type: integer minimum: 5 maximum: 600 - type: 'null' description: >- Seconds people get to answer; null means no countdown options: default: [] maxItems: 10 type: array items: type: string maxLength: 80 description: The answers to choose between, in order multiSelect: description: Let each person pick several options type: boolean correctIndex: description: >- Quiz: the index in options of the answer that scores type: integer minimum: 0 maximum: 9 quizView: description: >- Quiz: show the question, or the standings board type: string enum: - question - standings optionImages: description: >- Image choice: an image per option as a data URL, null for none maxItems: 10 type: array items: anyOf: - type: string maxLength: 500000 pattern: ^data:image\/.* - type: 'null' groups: description: >- 100 points: a parent group per option, for the nested looks maxItems: 10 type: array items: type: string maxLength: 40 targets: description: >- 100 points: a target per option, for the bullet look maxItems: 10 type: array items: type: number minimum: 0 maximum: 100 estimateMin: description: 'Estimate: the lowest guess allowed' type: number estimateMax: description: 'Estimate: the highest guess allowed' type: number answer: description: >- Estimate: the real answer, revealed when the poll closes type: number dimensions: description: >- Radar: the axes people rate 1 to 5, three to eight of them maxItems: 8 type: array items: type: string maxLength: 40 moderated: description: >- Hold submissions until the host approves them type: boolean wheelSource: description: >- Wheel: spin between everyone in the room, or a custom list type: string enum: - participants - custom wheelNames: description: 'Wheel: the custom names on the dial' maxItems: 20 type: array items: type: string maxLength: 40 place: description: 'Place map: the place people drop a pin on' type: object properties: label: type: string maxLength: 120 lat: type: number minimum: -90 maximum: 90 lon: type: number minimum: -180 maximum: 180 zoom: type: integer minimum: 1 maximum: 19 required: - label - lat - lon - zoom placeTheme: description: 'Place map: the map tiles' type: string enum: - standard - light - dark refs: description: >- Rounds: indexes of earlier poll steps to compare; empty means every poll before this one maxItems: 12 type: array items: type: integer minimum: 0 maximum: 199 accent: description: The result's accent colour type: string pattern: ^#[0-9a-fA-F]{6}$ colorMode: description: >- Colour options as shades of the accent (match) or as distinct hues (palette) type: string enum: - match - palette optionColors: description: >- A colour per option; null follows colorMode maxItems: 10 type: array items: anyOf: - type: string pattern: ^#[0-9a-fA-F]{6}$ - type: 'null' showPercent: description: Print percentages beside the answers type: boolean showCount: description: Print vote counts beside the answers type: boolean mcStyle: description: >- Result style: bars, lollipops, bubbles, spokes, butterfly, heat, arc, chord. arc needs multiSelect true; chord needs multiSelect true type: string enum: - bars - lollipops - bubbles - spokes - butterfly - heat - arc - chord imgStyle: description: 'Result style: tiles, mosaic, fill, hero' type: string enum: - tiles - mosaic - fill - hero totStyle: description: 'Result style: split, tug, camps' type: string enum: - split - tug - camps rankStyle: description: 'Result style: list, podium, avg' type: string enum: - list - podium - avg hpStyle: description: >- Result style: bars, treemap, waffle, columns, sunburst, marimekko, icicle, bullet type: string enum: - bars - treemap - waffle - columns - sunburst - marimekko - icicle - bullet scaleStyle: description: >- Style: stars, faces, breakdown, gauge, curve, bloom type: string enum: - stars - faces - breakdown - gauge - curve - bloom npsStyle: description: >- Result style: score, needle, diverging, swarm type: string enum: - score - needle - diverging - swarm estStyle: description: 'Result style: hist, curve, dots, range' type: string enum: - hist - curve - dots - range wcStyle: description: 'Result style: cloud, wordle, bubbles' type: string enum: - cloud - wordle - bubbles ofStyle: description: 'Result style: feed, cards, bubbles' type: string enum: - feed - cards - bubbles qaStyle: description: 'Style: list, spotlight' type: string enum: - list - spotlight mapStyle: description: 'Style: pins, heat, bars' type: string enum: - pins - heat - bars roundsMode: description: 'Chart: bump, stream, slope, dumbbell' type: string enum: - bump - stream - slope - dumbbell required: - type - prompt rect: default: x: 0.6 'y': 0.52 w: 0.36 h: 0.42 description: >- Where the card sits; left out, the bottom-right quarter type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h style: description: >- How the card is drawn; left out, the house default default: {} type: object properties: variant: default: bars description: The chart drawn on the card type: string enum: - bars - columns - donut - pie accent: default: '#3B82F6' type: string pattern: ^#[0-9a-fA-F]{6}$ background: default: '#FFFFFF' description: The card colour, or transparent for none anyOf: - type: string const: transparent - type: string pattern: ^#[0-9a-fA-F]{6}$ radius: default: 14 type: integer minimum: 0 maximum: 32 shadow: default: true type: boolean outline: default: false type: boolean outlineColor: default: '#E4E4E8' type: string pattern: ^#[0-9a-fA-F]{6}$ showPercent: default: true type: boolean showCount: default: true type: boolean showJoin: default: true description: Print the join code on the card type: boolean rotation: default: 0 description: Degrees type: number minimum: -180 maximum: 180 colorMode: type: string enum: - match - palette optionColors: description: >- A colour per option; null follows colorMode maxItems: 10 type: array items: anyOf: - type: string pattern: ^#[0-9a-fA-F]{6}$ - type: 'null' showTitle: description: Default true type: boolean titleFont: deprecated: true description: Retired; use textFont, the card's one face type: string maxLength: 80 titleSize: description: cqw type: number minimum: 1 maximum: 20 titleColor: type: string pattern: ^#[0-9a-fA-F]{6}$ titleBold: description: Default true type: boolean titleAlign: type: string enum: - left - center - right textFont: type: string maxLength: 80 z: description: Stacking order among the slide's elements type: number locked: default: false type: boolean prevRect: description: The size to restore after the full-page toggle type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h required: - poll texts: default: [] maxItems: 8 type: array items: type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 text: type: string maxLength: 300 rect: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h z: description: Stacking order among the slide's elements type: number style: type: object properties: size: type: number minimum: 1 maximum: 20 description: cqw, percent of slide width color: type: string pattern: ^#[0-9a-fA-F]{6}$ bold: type: boolean align: type: string enum: - left - center - right font: description: >- A library font key, or an uploaded family name type: string maxLength: 80 required: - size - color - bold - align required: - text - rect - style shapes: default: [] maxItems: 8 type: array items: type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 rect: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h z: description: Stacking order among the slide's elements type: number style: type: object properties: shape: type: string enum: - rect - ellipse - triangle - diamond fill: type: string pattern: ^#[0-9a-fA-F]{6}$ opacity: type: number minimum: 0.05 maximum: 1 radius: type: integer minimum: 0 maximum: 48 shadow: type: boolean outline: type: boolean outlineColor: type: string pattern: ^#[0-9a-fA-F]{6}$ required: - shape - fill - opacity - radius prevRect: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h required: - rect - style images: default: [] maxItems: 4 type: array items: type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 rect: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h z: description: Stacking order among the slide's elements type: number dataUrl: type: string maxLength: 12000000 pattern: ^data:image\/.* fit: description: >- Fill the frame (crop overflow) or show the whole image type: string enum: - cover - contain shadow: type: boolean outline: type: boolean outlineColor: type: string pattern: ^#[0-9a-fA-F]{6}$ radius: description: Corner rounding in px type: integer minimum: 0 maximum: 48 prevRect: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h original: description: The pre-crop copy, for Reset type: object properties: dataUrl: type: string maxLength: 12000000 pattern: ^data:image\/.* rect: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0.02 maximum: 1 h: type: number minimum: 0.02 maximum: 1 required: - x - 'y' - w - h required: - dataUrl - rect required: - rect - dataUrl notes: type: string maxLength: 2000 description: Presenter-only speaker notes required: - kind - pageIndex - overlays - type: object properties: id: description: Stable id. Omit it and the server makes one. type: string minLength: 1 maxLength: 64 kind: type: string const: poll poll: type: object properties: type: type: string enum: - multiple-choice - image-choice - this-or-that - ranking - hundred-points - rating - nps - estimate - radar - word-cloud - open-feed - qa-upvotes - timer - wheel - map - place-map - rounds prompt: type: string maxLength: 140 description: The question, as it reads on screen timeLimitSec: default: null anyOf: - type: integer minimum: 5 maximum: 600 - type: 'null' description: >- Seconds people get to answer; null means no countdown options: default: [] maxItems: 10 type: array items: type: string maxLength: 80 description: The answers to choose between, in order multiSelect: description: Let each person pick several options type: boolean correctIndex: description: >- Quiz: the index in options of the answer that scores type: integer minimum: 0 maximum: 9 quizView: description: 'Quiz: show the question, or the standings board' type: string enum: - question - standings optionImages: description: >- Image choice: an image per option as a data URL, null for none maxItems: 10 type: array items: anyOf: - type: string maxLength: 500000 pattern: ^data:image\/.* - type: 'null' groups: description: >- 100 points: a parent group per option, for the nested looks maxItems: 10 type: array items: type: string maxLength: 40 targets: description: >- 100 points: a target per option, for the bullet look maxItems: 10 type: array items: type: number minimum: 0 maximum: 100 estimateMin: description: 'Estimate: the lowest guess allowed' type: number estimateMax: description: 'Estimate: the highest guess allowed' type: number answer: description: >- Estimate: the real answer, revealed when the poll closes type: number dimensions: description: >- Radar: the axes people rate 1 to 5, three to eight of them maxItems: 8 type: array items: type: string maxLength: 40 moderated: description: Hold submissions until the host approves them type: boolean wheelSource: description: >- Wheel: spin between everyone in the room, or a custom list type: string enum: - participants - custom wheelNames: description: 'Wheel: the custom names on the dial' maxItems: 20 type: array items: type: string maxLength: 40 place: description: 'Place map: the place people drop a pin on' type: object properties: label: type: string maxLength: 120 lat: type: number minimum: -90 maximum: 90 lon: type: number minimum: -180 maximum: 180 zoom: type: integer minimum: 1 maximum: 19 required: - label - lat - lon - zoom placeTheme: description: 'Place map: the map tiles' type: string enum: - standard - light - dark refs: description: >- Rounds: indexes of earlier poll steps to compare; empty means every poll before this one maxItems: 12 type: array items: type: integer minimum: 0 maximum: 199 accent: description: The result's accent colour type: string pattern: ^#[0-9a-fA-F]{6}$ colorMode: description: >- Colour options as shades of the accent (match) or as distinct hues (palette) type: string enum: - match - palette optionColors: description: A colour per option; null follows colorMode maxItems: 10 type: array items: anyOf: - type: string pattern: ^#[0-9a-fA-F]{6}$ - type: 'null' showPercent: description: Print percentages beside the answers type: boolean showCount: description: Print vote counts beside the answers type: boolean mcStyle: description: >- Result style: bars, lollipops, bubbles, spokes, butterfly, heat, arc, chord. arc needs multiSelect true; chord needs multiSelect true type: string enum: - bars - lollipops - bubbles - spokes - butterfly - heat - arc - chord imgStyle: description: 'Result style: tiles, mosaic, fill, hero' type: string enum: - tiles - mosaic - fill - hero totStyle: description: 'Result style: split, tug, camps' type: string enum: - split - tug - camps rankStyle: description: 'Result style: list, podium, avg' type: string enum: - list - podium - avg hpStyle: description: >- Result style: bars, treemap, waffle, columns, sunburst, marimekko, icicle, bullet type: string enum: - bars - treemap - waffle - columns - sunburst - marimekko - icicle - bullet scaleStyle: description: >- Style: stars, faces, breakdown, gauge, curve, bloom type: string enum: - stars - faces - breakdown - gauge - curve - bloom npsStyle: description: 'Result style: score, needle, diverging, swarm' type: string enum: - score - needle - diverging - swarm estStyle: description: 'Result style: hist, curve, dots, range' type: string enum: - hist - curve - dots - range wcStyle: description: 'Result style: cloud, wordle, bubbles' type: string enum: - cloud - wordle - bubbles ofStyle: description: 'Result style: feed, cards, bubbles' type: string enum: - feed - cards - bubbles qaStyle: description: 'Style: list, spotlight' type: string enum: - list - spotlight mapStyle: description: 'Style: pins, heat, bars' type: string enum: - pins - heat - bars roundsMode: description: 'Chart: bump, stream, slope, dumbbell' type: string enum: - bump - stream - slope - dumbbell required: - type - prompt notes: type: string maxLength: 2000 description: Presenter-only speaker notes required: - kind - poll description: A step, exactly as in the document; ids may be left out at: description: Insert before this index. Left out, the step goes at the end type: integer minimum: 1 maximum: 9007199254740991 revision: description: >- The deck's revision you read (from get_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - step responses: '201': description: OK content: application/json: schema: type: object properties: index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Where it landed count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Steps in the deck now ready: type: boolean description: Every poll passes the readiness check, so a room can start problems: type: array items: type: object properties: step: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The step's index; 0 is the join screen overlay: description: Which card on the slide, when it is one type: integer minimum: -9007199254740991 maximum: 9007199254740991 path: type: string description: The property, from the step message: type: string description: What to do, in the editor's words required: - step - path - message additionalProperties: false description: What stops it, by step; empty when ready warnings: type: array items: type: object properties: element: type: string description: The element it is about, "overlay 0", "text 1" with: description: The other element, for an overlap type: string message: type: string description: What is wrong and what to do step: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The step's index required: - element - message - step additionalProperties: false description: >- Placements that will not read well on stage, by step: a card smaller than a fifth of the slide either way, or a card or text box over another card or text box. They do not stop a room; fix them anyway revision: type: string description: >- The deck's revision after this write; send it as `revision` with the next write to be sure nobody changed the deck in between required: - index - count - ready - problems - warnings - revision additionalProperties: false '400': description: The body did not fit. `fix` names the field. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: No usable key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The key lacks the scope, or the plan does not sell it. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Nothing by that id within this key's reach. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The deck changed since it was read: read it again with get_deck and send the new revision. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Over the key's hourly limit. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: error: type: string description: What went wrong, in a sentence fix: description: What to do about it, when we can tell type: string required: - error additionalProperties: false securitySchemes: apiKey: type: http scheme: bearer description: >- An API key from Settings › API, sent as `Authorization: Bearer ptr_…`. Shown once when made; only a hash is stored. ````