Create and update canvases

A canvas is the basic unit of CanvasMesh: a file + a renderer + a shareable URL. This guide shows how to create, update, and delete canvases across the CLI, SDK, and REST API.

Create

CLI

canvasmesh push ./report.md --title "Q2 Report"

Flags:

--title — human-readable title (defaults to filename)
--visibility — private (default) or public

SDK

const canvas = await client.create({
  title: 'Q2 Report',
  ext: 'md',
  content: '# Quarterly Report\n\n...',
});
console.log(canvas.view_url);

content accepts string, Blob, or ArrayBuffer. ext is the file extension without the dot — this is what CanvasMesh uses to pick a renderer.

REST

Upload the file first via the presigned flow, then create the canvas:

curl -X POST https://api.canvasmesh.app/v1/canvases \
  -H "Authorization: Bearer $CANVASMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "fl_xyz789",
    "title": "Q2 Report",
    "ext": "md"
  }'

The response includes canvas_id, version, and the resolved renderer.

Update

Updating a canvas creates a new version while keeping the same canvas_id and URL.

canvasmesh push ./report.md --id cv_abc123

await client.update('cv_abc123', {
  content: '# Updated content',
});

curl -X PUT https://api.canvasmesh.app/v1/canvases/cv_abc123 \
  -H "Authorization: Bearer $CANVASMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "fl_xyz789"}'

To only change metadata (title, visibility, renderer), omit file_id.

Temporary vs permanent

New canvases default to temporary — they expire 24 hours after creation. Pass permanent: true on create, or convert later:

curl -X POST https://api.canvasmesh.app/v1/canvases/cv_abc123/save \
  -H "Authorization: Bearer $CANVASMESH_API_KEY"

Permanent canvases do not expire.

List and delete

canvasmesh list --limit 50
canvasmesh pull cv_abc123 -o ./backup.md

const { canvases } = await client.list({ limit: 50 });
await client.delete('cv_abc123');

Delete is irreversible — all versions and share links are removed.