enhancedocs
For agentsOpen Enhance ↗
Reference / canvas.insertHtml

Enhance documentation

canvas.insertHtml

Compile one populated HTML subtree and atomically insert it at an explicit, revision-checked destination.

↓ Markdown

canvas.insertHtml

mutation write

Use when the requested change exactly matches canvas.insertHtml; read the current state first when a version or identifier may have changed.

Before calling

  • Authenticate as the accountable Enhance person.
  • Use only resource identifiers returned by an earlier capability result or supplied by the person.
  • Reuse clientToken only when retrying this exact mutation input.

Input

Show complete JSON Schema 
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"canvasRef":{"type":"string","minLength":1},"baseVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"destination":{"type":"object","properties":{"parentNodeId":{"type":"string","minLength":1,"description":"Existing editable container, or root for top-level insertion. Preserve page and selection scope."}},"required":["parentNodeId"],"additionalProperties":false},"html":{"type":"string","minLength":1,"description":"One populated, safe HTML/CSS visual group. Use authored positioning in the HTML for placement. The canonical compiler assigns fresh IDs."},"waitMs":{"default":1500,"description":"Additional polling after the initial server call; this does not bound initial compilation time.","type":"integer","minimum":0,"maximum":5000}},"required":["canvasRef","baseVersion","destination","html"],"additionalProperties":false}

Example

Show example input 
{
 "canvasRef": "00000000-0000-4000-8000-000000000010",
 "baseVersion": 1,
 "destination": {
  "parentNodeId": "root"
 },
 "html": "<div style=\"width:400px;height:200px\">Hello</div>",
 "waitMs": 1500
}

Result

Returns a typed canvas.insertHtml result from the Enhance API without transport-specific prose.

  • kind (required): Returned field kind.
  • state (required): Returned field state.
  • phase (required): Returned field phase.
  • requestedVersion (required): Returned field requestedVersion.
  • failure (required): Returned field failure.
  • operation (required): Returned field operation.
  • destination (required): Returned field destination.
  • result (required): Returned field result.
  • details (required): Returned field details.
  • warnings (required): Returned field warnings.
Show complete result JSON Schema 
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string","const":"canvas-conversion"},"state":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"]},"phase":{"type":"string","enum":["queued","claimed","grant","navigate","document","sources","fonts","layout","target","capture","serialize","compile","commit","upload","complete"]},"requestedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"failure":{"anyOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["VERSION_CHANGED","TARGET_NOT_FOUND","TARGET_INVALID","OUTPUT_TOO_LARGE","READINESS_TIMEOUT","SOURCE_FAILED","BROWSER_CRASH","CAPTURE_FAILED","CONVERSION_FAILED","PREPARATION_FAILED","UPLOAD_FAILED","WORKER_UNAVAILABLE","CANCELLED","EXPIRED","INTERNAL"]},"phase":{"type":"string","enum":["queued","claimed","grant","navigate","document","sources","fonts","layout","target","capture","serialize","compile","commit","upload","complete"]},"message":{"type":"string","minLength":1,"maxLength":500},"retryable":{"type":"boolean"},"sourceId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["reason","phase","message","retryable","sourceId"],"additionalProperties":false},{"type":"null"}]},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-conversion"},"canvasId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["kind","canvasId","jobId"],"additionalProperties":false},"destination":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"adjacent"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"insert-children"},"pageId":{"type":"string","minLength":1},"targetNodeId":{"type":"string","minLength":1}},"required":["kind","targetNodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"replace"},"targetNodeId":{"type":"string","minLength":1}},"required":["kind","targetNodeId"],"additionalProperties":false}]},"result":{"anyOf":[{"type":"object","properties":{"mutationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"previousVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"rootNodeId":{"type":"string"},"affectedBounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":0},"height":{"type":"number","minimum":0}},"required":["x","y","width","height"],"additionalProperties":false},"insertedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"removedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"identityCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"issueCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mutationId","previousVersion","version","rootNodeId","affectedBounds","insertedCount","removedCount","identityCount","issueCount"],"additionalProperties":false},{"type":"null"}]},"details":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"nextOffset":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"complete":{"type":"boolean"},"entries":{"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"inserted"},"nodeId":{"type":"string"}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"removed"},"nodeId":{"type":"string"}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"identity"},"temporaryId":{"type":"string"},"nodeId":{"type":"string"}},"required":["kind","temporaryId","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"issue"},"issue":{"type":"object","properties":{"code":{"type":"string","enum":["asset-unavailable","content-omitted","cross-origin-frame","nodes-truncated","responsive-behavior-not-editable","style-degraded","unsupported-surface"]},"message":{"type":"string","minLength":1},"temporaryId":{"type":"string","minLength":1}},"required":["code","message"],"additionalProperties":false}},"required":["kind","issue"],"additionalProperties":false}]}}},"required":["total","offset","nextOffset","complete","entries"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["kind","state","phase","requestedVersion","failure","operation","destination","result","details","warnings"],"additionalProperties":false}

Example result

Show example result 
{
 "kind": "canvas-conversion",
 "operation": {
  "kind": "canvas-conversion",
  "canvasId": "00000000-0000-4000-8000-000000000010",
  "jobId": "00000000-0000-4000-8000-000000000010"
 },
 "state": "queued",
 "phase": "queued",
 "requestedVersion": 1,
 "destination": {
  "kind": "insert-children",
  "targetNodeId": "root"
 },
 "result": null,
 "failure": null,
 "details": {
  "entries": [],
  "total": 0,
  "offset": 0,
  "nextOffset": null,
  "complete": true
 },
 "warnings": []
}

Recovery

  • BAD_REQUEST: correct the named fields and call again.
  • UNAUTHORIZED: restore Enhance authentication, then retry once.
  • FORBIDDEN or NOT_FOUND: check the supplied resource and selection; do not substitute unrelated content. Ask for corrected access or scope if needed.
  • CONFLICT: read the current resource, merge the intended change, and retry with its version.
  • INTERNAL: run Enhance diagnostics, report the failure, and stop repeating the call.

Continue with

  • Read the affected canvas resource to confirm the result.

Versions

Compatibility: 3b1c4d5d7f46f97399ed4f4f7a0f0cc8c2526d395e3796e138eef96ae54ba3f1.

Minimum tested versions: Enhance CLI and MCP runtime 0.1.40, plugin 1.0.38, Node.js 24. No older floor is published.