insertDiagramInDocument

{
  "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"
    },
    "documentVersionTimestamp": {
      "type": "number",
      "description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
    },
    "type": {
      "type": "string",
      "description": "Diagram type (e.g. mermaid, plantuml, bpmn, d2). Call listDiagramTypes for all types."
    },
    "diagramCode": {
      "type": "string",
      "description": "Diagram DSL code. Call getDiagramTypeGuide for syntax. EXCEPTION — for type 'infographic', put a plain-English DESCRIPTION of the infographic here (NOT code); the system designs the AntV spec and renders it."
    },
    "prompt": {
      "type": "string",
      "description": "Short description of what the diagram shows (1-2 sentences)."
    },
    "nlDescription": {
      "type": "string",
      "description": "Extended description of the diagram (2-4 sentences)."
    },
    "align": {
      "type": "string",
      "description": "Alignment.",
      "enum": [
        "left",
        "center",
        "right"
      ]
    },
    "caption": {
      "type": "string",
      "description": "Caption below the diagram."
    },
    "afterLine": {
      "type": "number",
      "description": "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."
    },
    "colorPlan": {
      "type": "object",
      "description": "BPMN only. Color plan: { byElementId: { ElementId: SwatchName } }.",
      "properties": {
        "byElementId": {
          "type": "object",
          "description": "Map of element IDs to color swatch names.",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "required": [
        "byElementId"
      ]
    },
    "returnImage": {
      "type": "boolean",
      "description": "If true, also render the inserted diagram and return it as an image inline (one-call insert-and-get-image). Defaults false."
    },
    "imageFormat": {
      "type": "string",
      "enum": [
        "png",
        "jpeg",
        "svg"
      ],
      "description": "Image format when returnImage:true (default png)."
    },
    "imageScale": {
      "type": "number",
      "enum": [
        1,
        2,
        3
      ],
      "description": "Raster resolution 1x/2x/3x when returnImage:true (default 2)."
    },
    "imageBackground": {
      "type": "string",
      "description": "Background for the returned png/jpeg (e.g. '#ffffff' or 'transparent')."
    },
    "applyBrandTheme": {
      "type": "boolean",
      "description": "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."
    },
    "brandKitId": {
      "type": "string",
      "description": "Optional brand kit UUID (see listBrandKits) to theme with instead of the cascade default. Must belong to your organisation."
    }
  },
  "required": [
    "documentId",
    "type",
    "diagramCode",
    "prompt"
  ]
}