> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/widgetic-api-public.json post /canvases openapi: 3.0.0 info: title: Widgetic API Gateway version: 1.0.0 description: API documentation for the Widgetic API Gateway license: name: Widgetic Integration License url: https://docs.widgetic.com/resources/license servers: - url: https://api.widgetic.com/v1 description: Production server variables: env: default: production description: Environment apiUrl: default: https://api.widgetic.com description: API URL apiVersion: default: /v1 description: API Version path prefix security: [] tags: [] paths: /canvases: post: tags: - Canvases summary: Create Canvas description: > 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. operationId: createCanvas requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCanvasRequest' responses: '201': description: Canvas created successfully content: application/json: schema: $ref: '#/components/schemas/CanvasResponse' '400': description: >- Invalid input (for example a `managedUserId` that is not a UUID, or both `managedUserId` and `managedUserExternalId`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The managed user named by `managedUserId` or `managedUserExternalId` is not one of yours (`MANAGED_USER_NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The managed user is switched off, so nothing new can be made for it (`MANAGED_USER_INACTIVE`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKeyAuth: [] x-code-samples: - lang: TypeScript label: TypeScript SDK source: | 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); } components: schemas: CreateCanvasRequest: type: object required: - persistenceKey properties: persistenceKey: type: string description: Key used for persistent storage and reference example: canvas_xyz123 canvasContent: type: object description: JSON content of the canvas, containing layout and configuration example: version: 1 elements: [] settings: {} primaryWidgetId: type: string format: uuid nullable: true description: Optional primary widget id (usually set after widget create) managedUserId: type: string format: uuid nullable: true description: >- 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: type: string maxLength: 255 nullable: true description: >- Make the canvas for the managed user you registered with this `externalId` (your own identifier for the user). Send this or `managedUserId`, not both. projectId: type: string format: uuid nullable: true description: >- Project this canvas belongs to. Empty canvases show on that project's list. example: persistenceKey: canvas_xyz123 canvasContent: version: 1 elements: [] settings: {} primaryWidgetId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 managedUserId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 managedUserExternalId: Example managedUserExternalId projectId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 CanvasResponse: type: object required: - success - data properties: success: type: boolean description: Always `true` on a success. example: true data: $ref: '#/components/schemas/Canvas' meta: $ref: '#/components/schemas/ResponseMeta' ErrorResponse: type: object required: - success - message - error additionalProperties: true properties: success: type: boolean description: Always `false` on a failure. example: false message: type: string description: The same text as `error.message`, for a caller that reads one line. error: $ref: '#/components/schemas/ErrorDetail' Canvas: type: object required: - id - persistenceKey - createdAt - updatedAt properties: id: type: string format: uuid description: Unique identifier for the canvas example: 123e4567-e89b-12d3-a456-426614174000 persistenceKey: type: string description: Key used for persistent storage and reference example: canvas_xyz123 canvasContent: type: object description: JSON content of the canvas, containing layout and configuration example: version: 1 elements: [] settings: {} creatorId: type: string format: uuid description: UUID of the user who created the canvas primaryWidgetId: type: string format: uuid nullable: true description: >- Primary widget for My widgets list and canvas-only deep-link (Convert per shape may add secondary widgets on the same canvas) example: 123e4567-e89b-12d3-a456-426614174099 managedUserId: type: string format: uuid nullable: true description: >- The managed user the canvas was made for (Widgetic's id for the user); null for a canvas that is the account's own. example: 123e4567-e89b-12d3-a456-426614174077 createdAt: type: string format: date-time description: Timestamp when the canvas was created example: '2023-01-01T00:00:00Z' updatedAt: type: string format: date-time description: Timestamp when the canvas was last updated example: '2023-01-02T00:00:00Z' 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' ResponseMeta: type: object description: >- 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. additionalProperties: true properties: page: type: integer description: The page that was read, counting from 1. example: 1 size: type: integer description: How many items one page holds. example: 20 total: type: integer description: How many items the whole list has. example: 135 limit: type: integer description: The same as `size`. example: 20 offset: type: integer description: How many items come before this page. example: 0 hasNextPage: type: boolean example: true hasPreviousPage: type: boolean example: false nextCursor: type: string nullable: true description: >- Pass this as `cursor` to read the next page of a list that is read by cursor. `null` on the last page. warnings: type: array items: type: string description: >- Things the call did not do, though it succeeded (for example a table that could not be created just now). ErrorDetail: type: object required: - code - message - timestamp properties: code: type: string description: Machine-readable error code. example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation. example: Composition not found param: type: string description: The field that caused the error, when one did. example: name docUrl: type: string description: Where this error is explained. suggestedAction: type: string description: What to do about it. retryAfter: type: integer description: >- Seconds to wait before trying again (rate limits). The same number is in the `Retry-After` header. example: 60 details: type: object additionalProperties: true description: >- More about the error: the fields that failed, a limit that was reached. correlationId: type: string description: Quote this when you ask support about the call. example: req_123e4567-e89b-12d3-a456-426614174000 timestamp: type: string format: date-time example: '2026-10-15T10:00:00.000Z' securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.