whiteboards

insertWhiteboardDiagram

Insert (or re-render in place) a real DIAGRAM (BPMN, Diagrams-as-Code / any DSL: mermaid, d2, plantuml, graphviz, …) on a whiteboard as an editable SB diagram element. Provide documentId, diagramType (call listDiagramTypes / getDiagramTypeGuide), and source (the DSL). The diagram is rendered to an image stored like a pasted image, and its editable source is kept in a sidecar so it stays a live, re-openable diagram (double-click on the canvas opens the BPMN / code / AI editor). Options: caption (label beneath it), width/height to size it (auto width caps at 480px; an explicit width may go up to 1200px), and x/y or align ('left'|'center'|'right') to place it (defaults to the right of existing content). Pass updateElementId to UPDATE an existing embedded diagram in place — re-render + replace its image and DSL while keeping the same element id and board position (used to live-edit a diagram as it evolves); if that id is not on the board yet it is created carrying that id. After inserting, call getWhiteboardImage to see it and verify it rendered correctly (fix the source and re-insert if it is wrong). For a plain picture (not a diagram) use insertWhiteboardImage; to generate a diagram image WITHOUT inserting use renderDiagram.

post/tools/insertWhiteboardDiagram

Request

  • Base URL: https://api.stablebaseline.io/functions/v1/cloud-serve/api/v1
  • URL: https://api.stablebaseline.io/functions/v1/cloud-serve/api/v1/tools/insertWhiteboardDiagram
  • Auth: HTTP bearer

Request body

documentIdstring required

The whiteboard's documentId.

diagramTypestring required

Diagram language, e.g. 'default', 'bpmn', 'mermaid', 'd2', 'plantuml', 'graphviz'. For a diagram family, use its defaultRenderer from listDiagramTypes.

sourcestring required

The diagram DSL / code. For 'default', provide MDP JSON with stable IDs and omit entity x/y for automatic layout; fully positioned manual sources remain valid; icons must be exact iconKey values from listArchitectureIcons. For 'infographic', provide a plain-English description instead (the system designs the infographic from it).

captionstring

Optional caption shown beneath the diagram.

widthnumber

Display width in px (aspect ratio preserved). Auto-size caps at 480px; an explicit width is honoured up to 1200px.

heightnumber

Display height in px (defaults from width + aspect).

xnumber

Top-left x on the canvas. Omit to auto-place (or to keep the existing position when updateElementId is given).

ynumber

Top-left y on the canvas. Omit to auto-place (or to keep the existing position when updateElementId is given).

align'left' | 'center' | 'right'

Horizontal alignment relative to existing content (placed below it). Ignored if x/y given.

updateElementIdstring

Element id of an EXISTING embedded diagram to re-render and replace in place (keeps the element id + board position). Omit for a fresh insert. If the id is not on the board, a new element is created with it.

applyBrandThemeboolean

Brand theming is ON BY DEFAULT: the board's effective BRAND KIT (colours only — typefaces are never injected) is baked into the diagram before it is rendered and its editable source stored (cascade: brandKitId override → project → workspace → org default → the built-in Stable Baseline theme). Set false to keep the library's stock styling. Themable types: mermaid, plantuml, graphviz, d2, systemsarchitecture, vega, vegalite, infographic; author theming in the DSL always wins.

brandKitIdstring

Optional brand kit UUID (see listBrandKits) to theme with instead of the cascade default. Must belong to your organisation.

fit'contain'

When 'contain' AND both width and height are given, treat width/height as a BOUNDING BOX: the diagram is scaled to its natural aspect ratio to fit inside the box (never upscaled past 1.5x natural) and centred, so it never stretches. The response's diagram.{x,y,width,height} carry the final drawn geometry. Omit for the exact width/height behaviour.

Response

Tool result (shape varies per tool — refer to the tool's docs for the exact return value).

object required

Changes

No recorded changes to this operation across all 1 revision of this API.