> ## 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. # Change a card > Change one card on a slide without resending the slide: the poll, where it sits (rect) or how it is drawn (style), each merged over what is there; what you leave out stays. Read the card's index with get_step. The way Paper's update_styles and move_nodes act on one node. Needs the `decks:write` scope. ## OpenAPI ````yaml https://test.polltheroom.com/openapi.json patch /api/v1/decks/{id}/steps/{index}/overlays/{card} 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}/overlays/{card}: patch: tags: - decks summary: Change a card description: >- Change one card on a slide without resending the slide: the poll, where it sits (rect) or how it is drawn (style), each merged over what is there; what you leave out stays. Read the card's index with get_step. The way Paper's update_styles and move_nodes act on one node. Needs the `decks:write` scope. operationId: update_overlay 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: 1 maximum: 9007199254740991 description: The slide step's index - name: card in: path required: true schema: type: integer minimum: 0 maximum: 9007199254740991 description: >- The card's index on the slide, counting from 0; read it with get_step requestBody: required: false content: application/json: schema: type: object properties: poll: description: Poll properties to change; the rest stay 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: anyOf: - type: integer minimum: 5 maximum: 600 - type: 'null' description: Seconds people get to answer; null means no countdown options: 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 rect: description: Where the card sits now 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: Style properties to change; the rest stay 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 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))$ responses: '200': description: OK content: application/json: schema: type: object properties: ok: type: boolean const: true card: 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 description: The card as it is 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: - ok - card - 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. ````