> ## 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. # Read one step > One step exactly as it is in the document, with its layout: every element's rect and which elements cover each other. Cheaper than get_deck when you work on one slide, and where you read a card's index before update_overlay or remove_overlay. Needs the `decks:read` scope. ## OpenAPI ````yaml https://test.polltheroom.com/openapi.json get /api/v1/decks/{id}/steps/{index} 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/{index}: get: tags: - decks summary: Read one step description: >- One step exactly as it is in the document, with its layout: every element's rect and which elements cover each other. Cheaper than get_deck when you work on one slide, and where you read a card's index before update_overlay or remove_overlay. Needs the `decks:read` scope. operationId: get_step parameters: - name: id in: path required: true schema: type: string minLength: 1 description: The deck's id - name: index in: path required: true schema: type: integer minimum: 0 maximum: 9007199254740991 description: The step's index; 0 is the join screen responses: '200': description: OK content: application/json: schema: type: object properties: index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 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: - id - kind additionalProperties: false 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 additionalProperties: false 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 - timeLimitSec - options additionalProperties: false 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 additionalProperties: false style: description: >- How the card is drawn; left out, the house 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 required: - variant - accent - background - radius - shadow - outline - outlineColor - showPercent - showCount - showJoin - rotation additionalProperties: false 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 additionalProperties: false required: - id - poll - rect - style - locked additionalProperties: false 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 additionalProperties: false 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 additionalProperties: false required: - id - text - rect - style additionalProperties: false 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 additionalProperties: false 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 additionalProperties: false 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 additionalProperties: false required: - id - rect - style additionalProperties: false 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 additionalProperties: false 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 additionalProperties: false 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 additionalProperties: false required: - dataUrl - rect additionalProperties: false required: - id - rect - dataUrl additionalProperties: false notes: type: string maxLength: 2000 description: Presenter-only speaker notes required: - id - kind - pageIndex - overlays - texts - shapes - images additionalProperties: false - 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 additionalProperties: false 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 - timeLimitSec - options additionalProperties: false notes: type: string maxLength: 2000 description: Presenter-only speaker notes required: - id - kind - poll additionalProperties: false elements: type: array items: type: object properties: id: type: string description: >- "overlay 0", "text 1": the list and the index, as the step verbs address it kind: type: string enum: - overlay - text - shape - image index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 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 additionalProperties: false z: type: number description: Stacking order; higher is on top label: type: string description: >- The card's question, the text box's first words, the shape's kind, or image required: - id - kind - index - rect - z - label additionalProperties: false overlaps: type: array items: type: object properties: a: type: string b: type: string covered: type: number description: >- How much of the smaller element the other covers, 0 to 1 required: - a - b - covered additionalProperties: false description: >- Pairs of elements that sit on top of each other; empty when nothing overlaps 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 required: - element - message additionalProperties: false description: >- What on this slide will not read well: a card too small to read, a card or text box over another 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 - step - elements - overlaps - warnings - revision additionalProperties: false '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' '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. ````