Canvas for AI agents

The Canvas skill teaches Codex, Claude and other coding agents to read a project, prepare prompts and references, wire nodes, and save with revision checks. Skills are the recommended starting point; MCP is optional.

Install the skillCopy Anchor Link

npx skills add https://docs.letsgen.app --skill letsgen-canvas

Choose your agent and installation scope. Use npx skills add https://docs.letsgen.app --list to discover both Canvas and generation skills. Installation itself does not connect your account or spend Gems.

Give the agent accessCopy Anchor Link

Create a personal key in Lets Gen Settings → API keys with read and Allow Canvas editing (canvas:write). Generation access is separate and can be turned off for project preparation. Existing keys do not acquire the new permission automatically: create a replacement when needed and revoke the old key when you no longer use it.

Store the secret as LETSGEN_API_KEY through your agent's secret settings or environment. Never paste it into the conversation, source code or a URL. Use Authorization: Bearer against https://letsgen.app. The key must belong to the same account that owns the project; account blocks, revocation and expiry still apply.

Copy the project ID from /canvas/PROJECT_ID. Ask the agent:

Use the letsgen-canvas skill to prepare this Canvas. Read its current graph and schema, preserve unrelated work, and save only my requested prompts and references. Leave generation and publishing to me.

Read and connectCopy Anchor Link

project contains projectId, title, revision, graph, connectionPorts, runStatuses and nodeRunStatuses. guide.graphSchema is the current graph input schema. Use endpoint-specific connectionPorts alongside connection rules; a schema enum is not a compatibility matrix. Run and node statuses can change without changing the graph revision.

Save an editCopy Anchor Link

Send the full graph read from the project, with only the requested edits:

{
  "revision": 7,
  "title": "My prepared storyboard",
  "graph": { "version": 4, "nodes": [], "edges": [] }
}

This empty graph illustrates the envelope only. Do not replace an existing project with it. Save bodies are limited to 2 MiB (413 when exceeded). title is optional; revision and graph are required. Preserve unrelated nodes, edges, group membership, existing references and output identities. Use only owned ready assets or permitted Characters. The server validates graph shape, wiring, owned sources and motion pointers before saving.

On success, use the returned canonical graph and revision for subsequent work. 409 REVISION_CONFLICT requires reading the project again and reconciling intervening edits. Never attach a newer revision to a stale graph. If a save response is lost, read the current project before deciding whether a retry is needed.

Wait for changesCopy Anchor Link

Pass the last cursor in /api/canvas/projects/PROJECT_ID/wait?cursor=CURSOR&timeoutMs=15000. timeoutMs accepts 0–20000 milliseconds and defaults to 15000. changed:false means timeout, not generation completion. Use one sequential wait at a time with backoff. Reads and waits never start, repair or advance generation.

Errors and limitsCopy Anchor Link

Missing, expired or revoked keys return 401. Missing permission or blocked account access returns 403. An unavailable or another account's project returns 404. Revision conflicts return 409. Invalid request bodies, graphs, wiring or owned inputs return 422. Temporary failures return 503; read before retrying a save. Errors use {error:{message,code}}.

This API prepares an existing project. Project creation, deletion, sharing, publication, extraction and media generation use the creator's Canvas controls. Canvas editing does not require generation permission or spend Gems. Direct generation uses the separate generation skill and an explicitly approved budget; its task does not automatically attach to a Canvas.

LLM referenceCopy Anchor Link

Every handbook page has a Read as Markdown link. llms-canvas.txt contains the complete Canvas handbook, including every node guide and this API contract. llms.txt indexes all docs; llms-full.txt includes the full site. OpenAPI covers the personal-key generation and Canvas APIs.

Optional MCP connectionCopy Anchor Link

Use https://mcp.letsgen.app/mcp with the same owner's account. The Canvas tools are connect_canvas_project, get_canvas_project, update_canvas_project and wait_canvas_project. Reads require mcp:read; saves additionally require mcp:canvas:write. Old authorizations may need reconnection for that write permission.

If your client lists only generation/media tools, refresh its server tool discovery and verify the configured endpoint. The current server contract includes all four Canvas tools; a stale deployment or cached client catalog can still omit them. Skill-based HTTP access avoids reliance on this tool catalog.

On MCP Apps hosts, Canvas results include a read-only visual graph preview, node details and a refresh action inside the host's app iframe. Open Canvas opens the full editor for creator review. The preview uses the authenticated tool result; it does not forward OAuth tokens into an embedded website or require third-party session cookies. Hosts without MCP Apps still receive structured graph data.