> ## 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. # Put text, a shape or a picture on a slide > Add one text box, shape or image to a slide without resending it: send exactly one of text, shape or image, as in the document. A card is added with add_overlay. Like a text box, a picture is placed by its rect; the slide clips what runs past it. Needs the `decks:write` scope. ## OpenAPI ````yaml https://test.polltheroom.com/openapi.json post /api/v1/decks/{id}/steps/{index}/elements 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}/elements: post: tags: - decks summary: Put text, a shape or a picture on a slide description: >- Add one text box, shape or image to a slide without resending it: send exactly one of text, shape or image, as in the document. A card is added with add_overlay. Like a text box, a picture is placed by its rect; the slide clips what runs past it. Needs the `decks:write` scope. operationId: add_element 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 requestBody: required: false content: application/json: schema: type: object properties: text: 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 shape: 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 image: 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 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: '201': description: OK content: application/json: schema: type: object properties: ok: type: boolean const: true kind: type: string enum: - text - shape - image element: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- The element's index in its list, for update_element and remove_element 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 - kind - element - 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 slide already holds as many of that kind as it may (8 text boxes, 8 shapes, 4 images), or 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. ````