> ## Documentation Index
> Fetch the complete documentation index at: https://widgetic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

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

## Canvas Structure

A canvas object contains:

```typescript theme={null}
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:

```json theme={null}
{
  "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:

```typescript theme={null}
// 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

> [card] [Widgets](https://widgetic.com/docs/api/widgets.md)
>
> Build widgets from canvases

> [card] [Compositions](https://widgetic.com/docs/api/compositions.md)
>
> Set a widget up for one place and embed it


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.