Canvases

Work with widget editing canvases

Canvases are the editing environment where widgets are designed and configured. Each canvas represents an editing session with its own state and widgets.

​

Overview

With the Canvases API, you can:

• Create new canvases
• List existing canvases
• Retrieve canvas details
• Update canvas content
• Delete canvases

​

List Canvases

Retrieve all canvases with pagination and filtering:

import { CanvasesApi } from '@widgetic/api-sdk-ts';

const canvases = new CanvasesApi('YOUR_API_KEY');

const { data, total } = await canvases.getAllCanvases({
  page: 1,
  size: 20,
  sort: 'created_at:desc'
});

console.log(`Found ${total} canvases, showing ${data?.length ?? 0}`);

​

Filtering Canvases

Filter canvases by various criteria:

const filtered = await canvases.getAllCanvases({
  createdAfter: new Date('2024-01-01T00:00:00Z'),
  createdBefore: new Date('2024-12-31T23:59:59Z'),
  updatedAfter: new Date('2024-06-01T00:00:00Z')
});

You can also filter by updatedBefore. The list cannot be filtered by persistence key.

​

Get Canvas by ID

Retrieve a specific canvas:

const canvas = await canvases.getCanvas({
  id: '123e4567-e89b-12d3-a456-426614174000'
});

console.log('Canvas:', canvas.persistenceKey);
console.log('Content:', canvas.canvasContent);

​

Create Canvas

Create a new canvas:

const newCanvas = await canvases.createCanvas({
  createCanvasRequest: {
    persistenceKey: 'my-widget-canvas-001',
    canvasContent: {
      version: 1,
      elements: [],
      settings: {
        background: '#ffffff',
        gridSize: 10
      }
    }
  }
});

console.log('Created canvas:', newCanvas.id);

​

Update Canvas

Update an existing canvas:

const updated = await canvases.updateCanvas({
  id: '123e4567-e89b-12d3-a456-426614174000',
  updateCanvasRequest: {
    canvasContent: {
      version: 2,
      elements: [
        { id: 'elem1', type: 'text', content: 'Hello' }
      ],
      settings: {
        background: '#f0f0f0',
        gridSize: 10
      }
    }
  }
});

​

Delete Canvas

Delete a canvas:

await canvases.deleteCanvas({
  id: '123e4567-e89b-12d3-a456-426614174000'
});

​

Canvas Structure

A canvas object contains:

interface Canvas {
  id: string;                    // Unique identifier
  persistenceKey: string;        // Your reference key
  canvasContent?: object;        // Canvas state (JSON)
  primaryWidgetId?: string | null; // The widget this canvas is mainly for
  creatorId?: string;            // Who made it
  createdAt: Date;               // Sent as an ISO timestamp
  updatedAt: Date;               // Sent as an ISO timestamp
}

​

Canvas Content

The canvasContent field stores the canvas state. It holds JSON of your choosing: the API saves what you send and does not check its shape. The examples above use this shape:

{
  "version": 1,
  "elements": [
    { "id": "elem1", "type": "text", "content": "Hello" }
  ],
  "settings": { "background": "#ffffff", "gridSize": 10 }
}

An update replaces canvasContent as a whole, so send all of it.

​

Persistence Keys

Use persistence keys to maintain references between your application and Widgetic:

// Create with a meaningful key
const canvas = await canvases.createCanvas({
  createCanvasRequest: {
    persistenceKey: `user_${userId}_project_${projectId}_canvas`,
    canvasContent: { version: 1, elements: [] }
  }
});

// Keep the id the API returns next to your own record (saveProjectRecord stands for your own storage code)
await saveProjectRecord({ projectId, widgeticCanvasId: canvas.id });

The list cannot be filtered by persistence key, so keep the id that creation returns in your own records.

​

Related Endpoints

Endpoint	Description
GET /canvases	List all canvases
GET /canvases/{id}	Get canvas by ID
POST /canvases	Create a new canvas
PUT /canvases/{id}	Update a canvas
DELETE /canvases/{id}	Delete a canvas

​

Next Steps

Widgets

Build widgets from canvases

Compositions

Set a widget up for one place and embed it