diagrams

updateDiagramInDocument

Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. New diagramCode is COMPILE-CHECKED BY RENDERING at write time — broken DSL is rejected with the renderer's error — and a valid change is re-rendered + re-thumbnailed immediately (response diagram.renderStatus tells you the outcome). Provide a version lock: diagramVersionTimestamp (from getDiagramInDocument, getDocument with includeDiagramDsl:true, or any diagram write's response — PREFERRED: locks just this diagram, so concurrent edits elsewhere in the document don't conflict; bare versionTimestamp is accepted as an alias) OR documentVersionTimestamp (locks the whole document). The response returns BOTH fresh tokens for chaining. Documents carrying a legacy marker (no embedded diagramId) are upgraded automatically on update. IMPORTANT: to change what the diagram visually shows you MUST provide diagramCode with the full updated DSL source — prompt/nlDescription are metadata only. After updating, view it with getDiagramImage and keep prompt/nlDescription in step with what the diagram now shows.

post/tools/updateDiagramInDocument

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

Request body

diagramIdstring required

Diagram ID from DIAGRAM_OMITTED markers.

diagramCodestring

New diagram DSL source code. REQUIRED to change what the diagram visually renders. Call getDiagramTypeGuide for syntax. Must provide the COMPLETE updated DSL, not just the changed parts. For 'default', provide complete MDP JSON and preserve stable IDs; omit entity x/y for automatic layout, or preserve all x/y in a manually positioned legacy diagram. Root layout.mode='auto' can explicitly rearrange an existing diagram. Its icons must be exact iconKey values from listArchitectureIcons. EXCEPTION: for type 'infographic', pass either a plain-English DESCRIPTION of the new infographic (the system designs, renders, and stores it, same as insert) or the complete infographic DSL (first line infographic <template-name>; getDiagramTypeGuide('infographic') has the grammar).

promptstring

New short description (metadata only — does NOT change the rendered diagram).

nlDescriptionstring

New extended description (metadata only — does NOT change the rendered diagram).

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

Alignment.

captionstring

New caption.

applyBrandThemeboolean

Brand theming is ON BY DEFAULT when diagramCode is provided: the document's effective BRAND KIT is baked into the new DSL before it is validated, rendered and stored. Set false to keep the library's stock styling. Same cascade + themable types + author-wins guards as insertDiagramInDocument. 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.

documentVersionTimestampnumber

Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required).

diagramVersionTimestampnumber

Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, getDocument with includeDiagramDsl:true, or a previous write's response). Preferred: locks only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. (Alias accepted: versionTimestamp.) The response returns the new diagram.versionTimestamp for chaining further edits.

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.