Skip to Content
AgentsRecipesInspect a canvas read-only

Inspect a Canvas Read-Only

The first thing to do with a new agent connection, and the first thing to do in any session before a write. Every call here is a read. Nothing is created, nothing is charged.

Scopes: canvas:read, asset:read. Cost: none.

Call sequence

canvas_list  →  canvas_get  →  canvas_validate  →  get_canvas_image or open_canvas

Or on the CLI:

canvas list  →  canvas get  →  connection list  →  canvas render  →  asset list

Steps

Find the canvas

MCP: call canvas_list.

CLI:

gavana canvas list --limit 25 --output human

Just the handles:

gavana canvas list --limit 25 --jq '.canvases[].handle' -r

Check before continuing. You need exactly one handle. If two canvases plausibly match the user’s description, ask which — do not pick. --limit here is capped at 25; continue with --cursor set to page.nextCursor if you need more.

Read the graph

MCP: canvas_get with the exact handle.

CLI:

gavana canvas get canvas:OWNER_UID:CANVAS_ID --pretty

Check before continuing. Note four things:

gavana canvas get canvas:OWNER_UID:CANVAS_ID --jq '.canvas.revision' -r
  • The revision — you will need it for any later write.
  • Node count and node types (text, sticky, image, video).
  • Which text nodes carry metadata.isSection: true — those are Sections, the canvas’s spatial structure.
  • The connections and their modes.

Audit the structure

MCP: canvas_validate with only the canvas id audits the current graph without proposing anything.

The result has a summary with errors, warnings, info, passed, and reviewRequired, plus a findings array. Each finding carries a code, a severity, exact node and connection handles, and a guideUri pointing at the guide topic that explains it.

Common codes and what they mean:

CodeMeaning
node_overlapTwo ordinary nodes overlap by more than 8 units in both directions
fake_section_headerA wide, short text node imitating a heading instead of being a Section
unconnected_generated_outputA generated image or video with no incoming relationship
orphan_media_placeholderAn empty media node with no relationship to a prompt, source, List, or stage
broken_connectionA connection pointing at a missing node
unclear_connectionA self-loop, a Section used as a workflow endpoint, or a wrong frame mode
duplicate_connectionTwo identical directed edges with the same mode
broken_generated_lineageA lineage reference in metadata pointing at a node that no longer exists
malformed_sectionA node marked as a Section that is not a text node of at least 200 by 160

Check before continuing. summary.passed means no structural error. summary.reviewRequired is true whenever errors, warnings, or truncated findings still need a human or agent look. Findings are advisory — they are review items, not a licence to start fixing the user’s canvas.

Validation never mutates the canvas and never consumes an idempotency key.

The CLI has no dedicated validate command. Use MCP canvas_validate, or the API with validateOnly: true. On a canvas you own you can reach it through the raw passthrough:

gavana api POST /canvases/CANVAS_ID/operations \
  --json '{"validateOnly":true,"operations":[{"type":"node.move","nodeId":"node:NODE_ID","position":{"x":0,"y":0}}]}'

Look at it

MCP: get_canvas_image returns a preview; open_canvas returns a verified review link for a human.

CLI:

gavana canvas render canvas:OWNER_UID:CANVAS_ID --file ./board.svg

Returns mediaType, the resolved file path, and bytes. Omit --file (or pass --file -) to get the SVG inline instead.

Check before continuing. Preview images are for review. They are not durable records — the node: and asset: handles are.

List the connections and assets

gavana connection list canvas:OWNER_UID:CANVAS_ID --jq '.connections[]' --output jsonl
gavana asset list --canvas canvas:OWNER_UID:CANVAS_ID --limit 50

connection list also returns the canvas handle and revision, so it doubles as a cheap revision check.

Report

Report using the exact returned handles, not titles or reconstructed ids.

What you end up with

  • The canvas handle and its current revision
  • Node and connection handles you can safely use in a later write
  • A structural assessment from canvas_validate
  • A review link or a rendered SVG for a human
  • Nothing changed, nothing charged

Prompt for an agent

Connect to Gavana in read-only mode. List my canvases, inspect the one most relevant
to [goal], and summarise its nodes, connections, current revision, and the safest
next step. Use the exact handles Gavana returns. Do not make changes and do not
start generation.

The expected trace is canvas_list then canvas_get, then optionally canvas_validate, get_canvas_image, or open_canvas. If you see a write tool in the trace, the agent went off contract.

Do this with a read-only connection

You do not need a full-scope credential for any of this:

  • Hosted MCP: stay on the read-only tools
  • CLI: gavana auth login --read-only
  • Local MCP: a token with only canvas:read and asset:read

Read-only is not a lesser version of inspection — it is the same reads with the write tools removed.

Continuing from here

If the review is all you needed, you are done. To create durable work, reconnect with a fuller endpoint or token and say explicitly what may happen next.

Save an imageBatch editsRun a Recipe
Last updated on
OverviewSave an image