ai-chatbot/integrations/openclaw/yedir-canvas/references/operation-protocol.md

CanvasOperationPlan reference

Required envelope

Every request passed to yedir_apply_canvas_operation has this shape:

{
  "canvasId": "canvas UUID",
  "operationPlan": {
    "version": 1,
    "operationId": "stable unique ID",
    "operation": "create_text_node",
    "projectId": "same canvas UUID",
    "baseCanvasRevision": "updatedAt from yedir_get_canvas",
    "baseCanvasUpdatedAt": "updatedAt from yedir_get_canvas",
    "textContent": "Example"
  }
}

operationId is the idempotency key. Keep it stable across retries of the same logical write.

Operations

Operation	Required fields	Notes
create_agent_slot	slot	slotType is image, video, or ui-screen.
create_text_node	textContent	Optional targetPosition or placement fields.
fill_slot	targetSlotId, media or mediaItems	Media type must match the slot.
insert_beside	anchorNodeId, media or mediaItems	Preserves the source.
append_revision	sourceNodeIds, media or mediaItems	Preferred for revised media.
replace_node_media	target, media, confirmed: true	Destructive; require explicit confirmation.
add_annotation	target and textContent or annotations	Annotation types: text-note, arrow-note, box, freehand, crop-box.
link_nodes	at least two targetNodeIds	Optional edgeType.
move_nodes	targets, targetPosition, confirmed: true	Require explicit confirmation.
delete_nodes	targets, confirmed: true	Require explicit confirmation.
rename_node	target and textContent	Changes the node title.
update_note	target and textContent	Updates note content.
update_text	target and textContent	Updates a text node.

Use targetNodeIds for mutations, sourceNodeIds for provenance, and anchorNodeId for relative placement. A request may reference at most 20 nodes or media items.

Placement

• placement: right, left, below, above, or viewport-center.
• placementStrategy: single, row, grid, overlay, or beside_each_source.
• layoutStrategy: row, column, or grid.
• spacing: positive number up to 240.

Media item

{
  "mediaItemId": "stable item ID",
  "type": "image",
  "url": "https://public-or-signed-media-url",
  "assetId": "optional UUID",
  "width": 1024,
  "height": 1024,
  "title": "Result",
  "prompt": "source prompt",
  "sourceNodeIds": ["source node ID"]
}

Only HTTP and HTTPS media URLs are accepted.