diagrams

insertDiagramInDocument

Insert a new diagram into a document. Call listDiagramTypes to find your type, then getDiagramTypeGuide for DSL syntax before writing diagramCode. The diagramCode is COMPILE-CHECKED BY RENDERING at write time: broken DSL is rejected with the renderer's error (fix and retry), and valid DSL is rendered + thumbnailed immediately so the document displays instantly everywhere. The response tells you what happened: diagram.renderStatus ('rendered' | 'pending_render' with renderError when the renderer was unavailable), plus fresh optimistic-lock tokens — document.versionTimestamp and diagram.versionTimestamp — so you can keep editing without re-reading. Always set prompt (and ideally nlDescription) to describe what the diagram shows. To SEE the result inline set returnImage:true, or call getDiagramImage afterwards; if it is wrong or ugly, correct it with updateDiagramInDocument (provide the full updated diagramCode).

post/tools/insertDiagramInDocument

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/insertDiagramInDocument
  • Auth: HTTP bearer

Request body

projectIdstring

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.

documentIdstring required
documentVersionTimestampnumber

Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)

typestring required

Diagram type, meaning the renderer (e.g. default, mermaid, plantuml, bpmn, d2; 'default' is the platform default renderer). For a diagram family such as a BPMN process, an ERD or a flowchart, use the family's defaultRenderer from listDiagramTypes or getDiagramTypeGuide. Call listDiagramTypes for all types.

diagramCodestring required

Diagram DSL code. Call getDiagramTypeGuide for syntax. For 'default', provide MDP JSON with stable IDs and omit every entity x/y for automatic layout; fully positioned manual diagrams are also supported, and icons must be exact iconKey values from listArchitectureIcons. EXCEPTION: for type 'infographic', put a plain-English DESCRIPTION of the infographic here (NOT code); the system designs the infographic and renders it.

promptstring required

Short description of what the diagram shows (1-2 sentences).

nlDescriptionstring

Extended description of the diagram (2-4 sentences).

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

Alignment.

captionstring

Caption below the diagram.

afterLinenumber

Insert after this line, counting the SAME line numbers getDocument prints (1-based; frontmatter is not counted, and every diagram/image marker counts as exactly one line). 0 inserts at the very beginning; omit it to append at the end. Re-read with getDocument if the document may have changed, since the number is positional.

returnImageboolean

If true, also render the inserted diagram and return it as an image inline (one-call insert-and-get-image). Defaults false.

imageFormat'png' | 'jpeg' | 'svg'

Image format when returnImage:true (default png).

imageScale1 | 2 | 3

Raster resolution 1x/2x/3x when returnImage:true (default 2).

imageBackgroundstring

Background for the returned png/jpeg (e.g. '#ffffff' or 'transparent').

applyBrandThemeboolean

Brand theming is ON BY DEFAULT: the document's effective BRAND KIT (colours only — typefaces are never injected) is baked into the diagram DSL before it is validated, rendered and stored, so the diagram is on-brand everywhere it appears (cascade: brandKitId override → project default → workspace default → 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 — other types (incl. bpmn, which has colorPlan) are always stored unchanged. Author theming in the DSL wins (an existing mermaid %%{init}%%, plantuml !theme, d2 vars.d2-config, or a hand-written infographic palette is never overridden). The stored diagramCode is the THEMED source.

brandKitIdstring

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

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.