Canvas Vision

Get started

Integrate Canvas Vision in five steps — from API key to your first POST /api/v1/agent call. For the full request and response reference, see the API docs.

  1. Create an API key

    Every call to POST /api/v1/agent requires a Bearer token. Create one in the dashboard after you have an account.

    Sign up or sign in, then open API keys and click Create key. Copy the secret immediately — it is shown only once.

    Open API keys

  2. Add canvas support

    Your whiteboard must expose the Canvas Window API so the pipeline can read layout and spatial structure. Install the official implement skill, then run /implement on your canvas page in your editor.

    Terminal
    npx skills add https://github.com/canvas-vision/canvas-vision-window-api-skill --skill implement

    Implementation by engine

    After the skill runs, your app should match the patterns below. These are abbreviated excerpts from this repo's live demos — not full files.

    Source: components/excalidraw-scene-embed/excalidraw-scene-embed-client.tsx

    // Attach when Excalidraw API is ready (excalidrawAPI callback)
const attachCanvasWindowApi = (api: ExcalidrawImperativeAPI) => {
  apiRef.current = api;

  window.getBounds = () => {
    const a = apiRef.current;
    if (!a) return { minX: 0, minY: 0, maxX: 0, maxY: 0 };
    const visible = getNonDeletedElements(a.getSceneElements());
    if (visible.length === 0) return { minX: 0, minY: 0, maxX: 0, maxY: 0 };
    const [minX, minY, maxX, maxY] = getCommonBounds(visible);
    return { minX, minY, maxX, maxY };
  };

  window.getViewport = () => {
    const s = api.getAppState();
    const zoom = s.zoom.value;
    return {
      x: -s.scrollX,
      y: -s.scrollY,
      width: s.width / zoom,
      height: s.height / zoom,
    };
  };

  window.setView = (xOrView, yArg) => {
    const { inputX, inputY } = parseSetViewInput(xOrView, yArg);
    api.updateScene({ appState: { scrollX: -inputX, scrollY: -inputY } });
  };

  window.canvasReady = true;
};

// Scene sync (demo hub): debounced PUT on onChange
await fetch(canvasDemoSceneApiPath(sessionId, "excalidraw"), {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ elements }),
});

    Excalidraw hub: scene debounce and PUT sync for the demo hub live in components/canvas-demo/excalidraw-hub-canvas.tsx (the embed file above registers the Window API).

    Docs: canvas-vision/canvas-vision-window-api-skill

    View skill on GitHub

  3. Expose a scannable canvas URL

    Pass a public HTTPS URL as canvas_url. The agent fetches that endpoint and scans canvas data — scene JSON, Window API payload, or equivalent. Not a login wall or empty shell.

    Use a stable route per board, e.g. https://your-app.com/api/canvas/session/abc/scene, and sync state before each agent call.

    This app's live demo uses routes like /api/canvas-demo/session/{id}/engine/{engine}/scene.

  4. Call POST /api/v1/agent

    Send only canvas_url and prompt in the JSON body. Replace the base URL with your Worker URL.

    curl -X POST "https://api.canvas-vision.com/api/v1/agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "canvas_url": "https://your-app.com/canvas/scene/abc",
    "prompt": "Summarize the architecture on this board."
  }'
    JSONSample 200 response
    Terminal
    {
  "answer": "The board shows three tiers: client, API gateway, and workers. Arrows indicate request flow from the browser through the gateway to async job processing.",
  "cache": "miss",
  "credits_charged": 1,
  "request_id": "req_01HZXK3N4WQ8R2M9P6Y7T0V"
}

    Full parameter list, response shape, model pricing, and capture recommendations live in the API reference.

    Open API reference

  5. What you can build

    In-canvas chat — Wire /api/v1/agent into a panel on your board (see the demo hub).

    Canvas understanding — Summarize diagrams, audit flows, or extract requirements without manual export.

    Agents & automation — Register the endpoint as a tool call so planners read the board before acting; point canvas_url at snapshots in CI.

    Open live demo