addWhiteboardElements

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
    },
    "documentId": {
      "type": "string"
    },
    "libavoidRoute": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Optional, used by the design worker's connector pass: route the batch's BOUND arrows and lines with the obstacle-aware libavoid router against the full scene before placing them (true), or 'force' to also discard hand-authored elbow points. Omit for the default as-authored routing. Declared because the tool rejects undeclared parameters and every builder-drawn arrow was failing on it (2026-09-09)."
    },
    "shapes": {
      "type": "array",
      "description": "Non-empty array of shape specs to append. Prefer stencils / sticky notes / architecture icons over raw rectangles wherever a standard form fits (see the `type` enum below and the tool description).",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "rectangle",
              "ellipse",
              "diamond",
              "sticky",
              "text",
              "arrow",
              "line",
              "freedraw",
              "doodle",
              "frame",
              "image",
              "stencil",
              "chart",
              "table"
            ],
            "description": "Element kind. 'sticky' = a first-class sticky/post-it note (solid fill + auto-fitting bound label; set text + backgroundColor) — use this for sticky notes, NOT a stencil. 'stencil' = a hand-drawn library graphic from listWhiteboardStencils, of kind 'symbol' (one atomic labelled node — flowchart box, BPMN task, org node: set `id` + `text` + width/height, text auto-fits, connect arrows via start/end {id}) or 'template' (a multi-element layout — Alerts, Forms, Tables, Charts: place whole, then customise its returned children by id; do NOT set a single `text`). Set `stencil` (fuzzy name, one call) or `stencilKey` (exact). 'image' with `iconPath` = a software-architecture icon from listArchitectureIcons. 'chart' = a NATIVE, fully-editable data chart (column/bar/line/area/pie/donut/scatter/sparkline/combo/stackedColumn/groupedColumn/radar/gauge) built from real Excalidraw shapes — bars/lines/wedges plus axes, gridlines and a legend — for ANY data, metric, KPI, trend, comparison or breakdown: set chartType + series (+ categories + options). ALWAYS prefer a 'chart' over hand-drawing bars/lines or a wireframe 'chart' stencil. 'table' = a NATIVE, fully-editable GRID (real rectangles + bound, word-wrapped cells, auto-sized columns + rows, a header band, optional zebra striping / per-column colours) for ANY tabular data, list or matrix — set columns + rows (+ options). ALWAYS prefer a 'table' over hand-drawing a grid of boxes. Reserve rectangle/ellipse/diamond for when no standard form fits."
          },
          "stencil": {
            "type": "string",
            "description": "For type:'stencil' — fuzzy-match a library stencil by name in ONE call, no prior listWhiteboardStencils needed (e.g. 'decision', 'actor', 'phone frame', 'kanban column'). NOTE: there is no sticky-note stencil — use type:'sticky' for sticky/post-it notes."
          },
          "stencilKey": {
            "type": "string",
            "description": "For type:'stencil' — exact stencil key from listWhiteboardStencils (takes precedence over `stencil`)."
          },
          "pack": {
            "type": "string",
            "description": "For type:'stencil' — optional pack to disambiguate a fuzzy `stencil` match (e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board')."
          },
          "iconPath": {
            "type": "string",
            "description": "For type:'image' — a software-architecture icon path from listArchitectureIcons (e.g. 'dev/docker.svg')."
          },
          "imageUrl": {
            "type": "string",
            "description": "For type:'image' — any other public image URL (use iconPath for curated architecture icons)."
          },
          "doodle": {
            "type": "string",
            "description": "For type:'doodle' — a named hand-drawn accent rendered as a freehand stroke (no points needed): 'underline' | 'wave' | 'arrow' | 'check' | 'bolt' | 'scribble' | 'star' | 'sparkle' | 'circle' (a ring to encircle/emphasise) | 'heart'. Size it with x/y + width/height and colour it with strokeColor. Great for sketchy emphasis (underline a title, circle a stat, a star/sparkle accent)."
          },
          "id": {
            "type": "string",
            "description": "Optional id so connectors (arrows/lines) can reference this shape via start/end. On a type:'stencil' it adds a transparent bindable anchor covering the stencil, so an arrow's start/end {id} connects to the whole stencil as a unit."
          },
          "groupId": {
            "type": "string",
            "description": "Join an existing group. Pass a placed stencil's `groupId` (returned in the placement result) on a type:'text' or shape spec to FILL that frame as part of the same unit — the text then moves, duplicates and renders together with the frame (e.g. a title in a UML class box's top band, members in its body)."
          },
          "x": {
            "type": "number",
            "description": "Top-left x on the canvas. OMIT both x and y to auto-place this element in clear empty space below the board's existing content. Strongly preferred when adding a note/shape to a board that already has content: a guessed coordinate usually lands ON TOP of existing shapes (the 'added a sticky but can't see it' bug). Set x/y only for deliberate layout among shapes you add in this same call."
          },
          "y": {
            "type": "number",
            "description": "Top-left y on the canvas. Omit together with x to auto-place (see x)."
          },
          "width": {
            "type": "number",
            "description": "Shape width; for type:'stencil' it scales the whole stencil to fit this width."
          },
          "height": {
            "type": "number",
            "description": "Shape height; for type:'stencil' it scales the whole stencil to fit this height."
          },
          "scale": {
            "type": "number",
            "description": "For type:'stencil' — uniform scale factor for the whole stencil (alternative to width/height)."
          },
          "text": {
            "type": "string",
            "description": "Label/caption. To label a shape, set `text` on the SHAPE itself — it becomes a BOUND label that the server word-wraps with real font metrics, auto-fits, and positions (centred by default) INSIDE the shape. Never drop a separate type:'text' element on top of a shape, and never hand-compute a label's x/y/width — the server does the geometry (like the editor does when you type into a shape). On a type:'sticky' it's the note text; on a type:'stencil' of kind 'symbol' it fills + re-fits its single label (IGNORED for 'template' stencils — customise their children by id instead). Use a standalone type:'text' only for free-floating text that belongs to no shape."
          },
          "fitText": {
            "type": "boolean",
            "description": "Auto-shrink the bound label's font size so the text always fits inside the shape — no overflow (default true). Set false to keep your exact fontSize even if it spills."
          },
          "fontSize": {
            "type": "number",
            "description": "Text size in px. Establish HIERARCHY: titles ~28-40, section headings ~22-28, body/labels ~16-20. Applies to a standalone text, a shape's bound label, a sticky, or an icon caption. Bound labels still auto-shrink to fit unless fitText:false."
          },
          "fontFamily": {
            "type": "string",
            "description": "Font style: 'hand-drawn' (sketchy Excalidraw look, the default), 'sans' (clean/professional — use for business, dashboards, formal diagrams), or 'code' (monospace). Pass this to control the look instead of leaving everything hand-drawn."
          },
          "strokeColor": {
            "type": "string",
            "description": "TEXT colour (for text/labels) or line/border colour (for shapes, arrows, lines, doodles): a name ('blue'/'green'/'red'/'orange'/'violet'/'teal'/…) or a hex value. Use a brand or theme colour for titles/emphasis; default is near-black."
          },
          "textAlign": {
            "type": "string",
            "enum": [
              "left",
              "center",
              "right"
            ],
            "description": "Horizontal alignment of the text within its box — the equivalent of the toolbar's align buttons. Bound labels default to 'center'."
          },
          "verticalAlign": {
            "type": "string",
            "enum": [
              "top",
              "middle",
              "bottom"
            ],
            "description": "Vertical alignment of a bound label inside its shape (toolbar parity). Defaults to 'middle' (centred)."
          },
          "backgroundColor": {
            "type": "string",
            "description": "Fill colour: a name ('blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/…) or a hex value."
          },
          "start": {
            "type": "object",
            "description": "For arrows/lines: { id } of the source shape (auto-clips to the edge + auto-routes around shapes in between)."
          },
          "end": {
            "type": "object",
            "description": "For arrows/lines: { id } of the target shape."
          },
          "title": {
            "type": "string",
            "description": "For type:'chart' — the chart's title, drawn at the top of the chart."
          },
          "chartType": {
            "type": "string",
            "enum": [
              "column",
              "bar",
              "line",
              "area",
              "pie",
              "donut",
              "scatter",
              "sparkline",
              "combo",
              "stackedColumn",
              "groupedColumn",
              "radar",
              "gauge"
            ],
            "description": "For type:'chart' — the chart family. column=vertical bars (default), bar=horizontal bars, line/area=trends, pie/donut=parts-of-whole, scatter=points, sparkline=tiny inline trend (no axes/legend), combo=bars+line (dual axis via a series with axis:'right'), stackedColumn/groupedColumn=multi-series, radar, gauge."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "For type:'chart' — x-axis category labels, e.g. ['Jan','Feb','Mar','Apr']."
          },
          "series": {
            "type": "array",
            "description": "For type:'chart' — one or more data series. Each: { name:string, data:number[], type?:'bar'|'line'|'area' (per-series, for combo), color?:string (hex), axis?:'left'|'right' (dual axis), markers?:boolean (line point markers) }. For pie/donut use ONE series whose data maps to categories.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "options": {
            "type": "object",
            "description": "For type:'chart' — { legend?:boolean|'top'|'bottom'|'right', gridlines?:boolean|'x'|'y'|'both'|'none', dataLabels?:boolean, yAxis?:boolean, xAxis?:boolean, yMin?:number, yMax?:number, smooth?:boolean, valueFormat?:'%'|'$'|'k', palette?:string[] (hex), donutHole?:number }. For type:'table' — { headerFill?:string (hex), headerTextColor?:string, zebra?:boolean, rowFill?:string, altRowFill?:string, columnColors?:string[] (per-column hex), fontSize?:number, headerFontSize?:number, borderColor?:string, align?:'left'|'center'|'right' }.",
            "additionalProperties": true
          },
          "columns": {
            "type": "array",
            "description": "For type:'table' — column headers: string[] (e.g. ['Task','Owner','Status']) or [{ header:string, width?:number, align?:'left'|'center'|'right' }].",
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "object"
                }
              ]
            }
          },
          "rows": {
            "type": "array",
            "description": "For type:'table' — data rows; each row is an array of cell values (string|number) aligned to columns, e.g. [['T-1','Sam','Done'],['T-2','Lee','WIP']].",
            "items": {
              "type": "array",
              "items": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ]
              }
            }
          },
          "customData": {
            "type": "object",
            "description": "Arbitrary Excalidraw customData stored on the element (e.g. a slide frame's { deckId } so a board frame resolves back to its source deck). Merged with any builder-set customData.",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "minItems": 1
    }
  },
  "required": [
    "documentId",
    "shapes"
  ]
}