Create Canvas

Creates a new canvas with the specified properties.

To make the canvas for one of your managed users, send managedUserId or managedUserExternalId. The canvas stays in your account and is yours to edit; the tag lets you list one user’s canvases with getAllCanvases. The managed user must be yours and active: one that is not yours, or does not exist, is answered with 404 and MANAGED_USER_NOT_FOUND, and one that is switched off with 409 and MANAGED_USER_INACTIVE. The tag is set here and does not change afterwards. Called with an editor session, the canvas is always made for the session’s managed user.

POST /canvases

TypeScript SDK

TypeScript

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

const config = new Configuration({
  apiKey: 'YOUR_API_KEY'
});

const canvasesApi = new CanvasesApi(config);

try {
  const canvas = await canvasesApi.createCanvas({
    createCanvasRequest: {
      persistenceKey: "canvas_xyz123",
      canvasContent: { version: 1, elements: [], settings: {} }
    }
  });
  console.log('Created canvas:', canvas);
} catch (error) {
  console.error('Failed to create canvas:', error);
}

201

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "persistenceKey": "canvas_xyz123",
    "canvasContent": {
      "version": 1,
      "elements": [],
      "settings": {}
    },
    "creatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "primaryWidgetId": "123e4567-e89b-12d3-a456-426614174099",
    "managedUserId": "123e4567-e89b-12d3-a456-426614174077",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-02T00:00:00Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

persistenceKey · string · required

Key used for persistent storage and reference

Example:

"canvas_xyz123"

canvasContent · object

JSON content of the canvas, containing layout and configuration

Example:

{
  "version": 1,
  "elements": [],
  "settings": {}
}

primaryWidgetId · string<uuid> | null

Optional primary widget id (usually set after widget create)

managedUserId · string<uuid> | null

Make the canvas for this managed user (Widgetic's id for the user). Send this or managedUserExternalId, not both. The tag is set here and does not change afterwards.

managedUserExternalId · string | null

Make the canvas for the managed user you registered with this externalId (your own identifier for the user). Send this or managedUserId, not both.

Maximum string length: 255

projectId · string<uuid> | null

Project this canvas belongs to. Empty canvases show on that project's list.

Response

201

application/json

Canvas created successfully

success · boolean · required

Always true on a success.

Example:

true

data · object · required

Show child attributes

Example:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "persistenceKey": "canvas_xyz123",
  "canvasContent": {
    "version": 1,
    "elements": [],
    "settings": {}
  },
  "creatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "primaryWidgetId": "123e4567-e89b-12d3-a456-426614174099",
  "managedUserId": "123e4567-e89b-12d3-a456-426614174077",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T00:00:00Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes