Skip to content

Canvases

A canvas is the core workspace in Canvus. It is an infinite, zoomable surface where users place and arrange content -- notes, images, videos, PDFs, browser windows, connectors, and more. Every piece of content on a canvas is a widget.

Canvases live inside folders (see Canvas Folders). Each canvas has an owner, a set of permissions, and optional shared link access. Canvases can operate in normal mode or demo mode, which allows saving and restoring a snapshot of the canvas state for repeatable presentations.

All endpoints below are prefixed with /api/v1.

Authentication

Most canvas endpoints require a Private-Token header containing a valid API access token.

Private-Token: YOUR_TOKEN

Exception -- shared links: If a canvas has its link_permission set to view or edit, the Private-Token header may be omitted. In that case, access is granted as the Guest user with the corresponding permission level. If the Guest user is blocked on the server, unauthenticated access is unavailable. If a valid token is provided alongside a shared link, the authenticated user's permissions apply, but are never lower than the link permission. The move, copy, save, restore, and permissions endpoints always require a token.

Current behavior

An invalid or expired token currently returns 403 Forbidden, not the 401 listed for each endpoint below. See Current behavior.

Streaming (long-polling)

GET endpoints that list this as supported accept a ?subscribe query parameter. When present, the server holds the connection open and streams JSON updates as newline-delimited JSON, with keepalive pings at a configurable interval (default 15 seconds). See the Streaming documentation for details.

Canvas object

Canvas objects returned by the API include these fields. Fields with no value (for example an empty name, folder_id or access, or an unset timestamp) are omitted.

  • id (string) -- UUID identifying the canvas
  • name (string) -- display name
  • folder_id (string) -- ID of the parent folder
  • access (string) -- the requesting user's effective permission (owner, edit, view, none)
  • mode (string) -- normal or demo
  • state (string) -- canvas state: normal. In streamed updates, deleted means the canvas was deleted; that event carries only id and state.
  • in_trash (boolean) -- whether the canvas is in the trash
  • asset_size (integer) -- total size of assets on the canvas in bytes
  • preview_hash (string) -- hash of the preview image, empty string if no preview exists
  • created_at (string) -- ISO 8601 creation timestamp
  • modified_at (string) -- ISO 8601 last-modified timestamp

List canvases

Returns all canvases visible to the authenticated user.

GET /api/v1/canvases
  • Authentication: Required
  • Streaming: Supported

Query parameters:

  • subscribe (flag, optional) -- enable streaming. Streaming is enabled whenever the parameter is present; its value is ignored.

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases

Response: 200 OK

[
  {
    "access": "owner",
    "asset_size": 0,
    "created_at": "2025-03-15T09:12:04.426Z",
    "folder_id": "1034",
    "id": "020b063d-0086-49a5-8dd0-965b8e117216",
    "in_trash": false,
    "mode": "normal",
    "modified_at": "2025-03-15T09:12:04.426Z",
    "name": "Q1 Planning",
    "preview_hash": "a3f8c91b2e07",
    "state": "normal"
  },
  {
    "access": "edit",
    "asset_size": 52428800,
    "created_at": "2025-03-10T14:30:00.000Z",
    "folder_id": "1034",
    "id": "9c21f153-ac8b-4ad3-83c5-60c282ee9359",
    "in_trash": false,
    "mode": "demo",
    "modified_at": "2025-03-14T16:45:22.100Z",
    "name": "Showroom Demo",
    "preview_hash": "f7e2d4a8b103",
    "state": "normal"
  }
]

Error responses:

  • 401 Unauthorized -- missing or invalid token

Get a single canvas

Returns details for one canvas.

GET /api/v1/canvases/:canvas_id
  • Authentication: Required (unless canvas has a shared link)
  • Streaming: Supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Query parameters:

  • subscribe (flag, optional) -- enable streaming. Streaming is enabled whenever the parameter is present; its value is ignored.

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216

Response: 200 OK

{
  "access": "owner",
  "asset_size": 0,
  "created_at": "2025-03-15T09:12:04.426Z",
  "folder_id": "1034",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2025-03-15T09:12:04.426Z",
  "name": "Q1 Planning",
  "preview_hash": "a3f8c91b2e07",
  "state": "normal"
}

Error responses:

  • 401 Unauthorized -- missing or invalid token (and no shared link)
  • 404 Not Found -- canvas does not exist

Get canvas preview

Downloads the canvas preview image as a file, if one has been generated. Preview images are created automatically by connected Canvus clients.

GET /api/v1/canvases/:canvas_id/preview
  • Authentication: Required (unless canvas has a shared link)
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

curl example:

curl -H "Private-Token: YOUR_TOKEN" -o preview.png \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/preview

Response: 200 OK with binary image data and Content-Disposition header.

If no preview is available:

{
  "msg": "Canvas 020b063d-0086-49a5-8dd0-965b8e117216 doesn't have preview"
}

Error responses:

  • 401 Unauthorized -- missing or invalid token (and no shared link)
  • 404 Not Found -- canvas does not exist

Create a canvas

Creates a new canvas. If no folder_id is specified, the canvas is created in the authenticated user's home folder.

POST /api/v1/canvases
  • Authentication: Required
  • Streaming: Not supported

Request body (JSON):

  • name (string, optional) -- name for the new canvas. Server assigns a default name if omitted
  • folder_id (string, optional) -- ID of the parent folder
  • size (object, optional) -- canvas size in pixels, as {"width": 9600, "height": 5400}. Both width and height must be given; otherwise the default of 9600 x 5400 is used. The minimum is 1200 x 800; smaller values return 400 Bad Request.

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sprint Retro", "folder_id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3"}' \
  https://canvus.example.com/api/v1/canvases

Response: 200 OK

{
  "access": "owner",
  "asset_size": 0,
  "created_at": "2025-03-20T10:00:00.000Z",
  "folder_id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
  "id": "70c54ca9-a31d-45d8-af84-bacc9b708caf",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2025-03-20T10:00:00.000Z",
  "name": "Sprint Retro",
  "preview_hash": "",
  "state": "normal"
}

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions on target folder

Update a canvas

Renames a canvas or changes its mode between normal and demo. Change one property per request: a request that changes both name and mode returns 400 Bad Request. You cannot change folder_id with this endpoint; use Move Canvas or Copy Canvas instead.

PATCH /api/v1/canvases/:canvas_id
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Request body (JSON):

  • name (string, optional) -- new name for the canvas
  • mode (string, optional) -- normal or demo

Mode values:

  • normal -- canvas is a regular canvas
  • demo -- canvas is a demo canvas (supports save/restore)

curl example:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 Planning - Final"}' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216

Response: 200 OK

{
  "access": "owner",
  "asset_size": 0,
  "created_at": "2025-03-15T09:12:04.426Z",
  "folder_id": "1034",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2025-03-20T11:30:00.000Z",
  "name": "Q1 Planning - Final",
  "preview_hash": "a3f8c91b2e07",
  "state": "normal"
}

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist

Delete a canvas

Permanently deletes a canvas and all of its contents. This action is irreversible. To move a canvas to the trash instead (recoverable), see Trash a Canvas.

DELETE /api/v1/canvases/:canvas_id
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

curl example:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216

Response: 200 OK (empty body)

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist

Current behavior

A caller who may not delete the canvas currently gets 404 Not Found rather than 403 Forbidden. This is being corrected.

Move canvas

Moves a canvas to a different folder.

POST /api/v1/canvases/:canvas_id/move
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas to move

Request body (JSON):

  • folder_id (string, required) -- the destination folder ID
  • conflicts (string, optional) -- conflict resolution strategy (default: skip)

Current behavior

folder_id is not yet enforced: a request without it (and with no other change) returns 200 OK and leaves the canvas where it is. This is being corrected.

Conflict resolution values:

  • skip -- skip the canvas if a name conflict exists in the destination; the request does not fail (default)
  • cancel -- cancel the operation with 409 Conflict if a name conflict exists in the destination
  • replace -- replace the conflicting canvas in the destination

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "47c0e2cb-a299-4f3b-ac9a-810cc7c242d3", "conflicts": "replace"}' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/move

Response: 200 OK

{
  "access": "owner",
  "asset_size": 0,
  "created_at": "2025-03-15T09:12:04.426Z",
  "folder_id": "47c0e2cb-a299-4f3b-ac9a-810cc7c242d3",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2025-03-15T09:12:04.426Z",
  "name": "Q1 Planning",
  "preview_hash": "a3f8c91b2e07",
  "state": "normal"
}

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions on source or destination
  • 404 Not Found -- canvas or folder does not exist
  • 409 Conflict -- name conflict and conflicts is cancel

Copy canvas

Copies a canvas to another folder. All widgets and assets are duplicated. Copying a canvas to the same folder it already lives in creates a duplicate.

POST /api/v1/canvases/:canvas_id/copy
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas to copy

Request body (JSON):

  • folder_id (string, required) -- the destination folder ID
  • conflicts (string, optional) -- conflict resolution strategy (default: skip)

Current behavior

folder_id is not yet enforced: a request without it (and with no other change) returns 200 OK and leaves the canvas where it is. This is being corrected.

Conflict resolution values:

  • skip -- skip the canvas if a name conflict exists in the destination; the request does not fail (default)
  • cancel -- cancel the operation with 409 Conflict if a name conflict exists in the destination
  • replace -- replace the conflicting canvas in the destination

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "47c0e2cb-a299-4f3b-ac9a-810cc7c242d3"}' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/copy

Response: 200 OK -- returns the newly created canvas object.

{
  "access": "owner",
  "asset_size": 0,
  "created_at": "2025-03-20T12:00:00.000Z",
  "folder_id": "47c0e2cb-a299-4f3b-ac9a-810cc7c242d3",
  "id": "c4a91e3f-7b2d-48a0-9f15-3e8d72c1a5b6",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2025-03-20T12:00:00.000Z",
  "name": "Q1 Planning",
  "preview_hash": "",
  "state": "normal"
}

Current behavior

When you copy a canvas into the folder it is already in, the response currently contains the original canvas rather than the new copy. List the folder to find the copy. This is being corrected.

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas or folder does not exist
  • 409 Conflict -- name conflict and conflicts is cancel

Trash a canvas

Moves a canvas to the user's trash folder. This is a soft delete -- the canvas can be restored by moving it back out of trash. Use the Move Canvas endpoint with the trash folder ID.

The conflicts parameter is ignored when moving to trash. Regular users cannot move items to another user's trash folder; administrators can.

POST /api/v1/canvases/:canvas_id/move
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas to trash

Request body (JSON):

  • folder_id (string, required) -- the trash folder ID (format: trash.<user-id>)

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "trash.1034"}' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/move

Response: 200 OK

{
  "access": "owner",
  "asset_size": 0,
  "created_at": "2025-03-15T09:12:04.426Z",
  "folder_id": "trash.1034",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": true,
  "mode": "normal",
  "modified_at": "2025-03-15T09:12:04.426Z",
  "name": "Q1 Planning",
  "preview_hash": "a3f8c91b2e07",
  "state": "normal"
}

Permissions

Canvas permissions control who can view, edit, or manage a canvas. Permissions are assigned per-user or per-group, and optionally via shared links.

Permission levels

  • none -- no access
  • view -- read-only access
  • edit -- can modify canvas content
  • owner -- full control including permission management and deletion

Get canvas permissions

Returns the permission configuration for a canvas, including per-user overrides, per-group overrides, and the shared link setting.

GET /api/v1/canvases/:canvas_id/permissions
  • Authentication: Required
  • Streaming: Supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Query parameters:

  • subscribe (flag, optional) -- enable streaming. Streaming is enabled whenever the parameter is present; its value is ignored.

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/permissions

Response: 200 OK

{
  "editors_can_share": true,
  "link_permission": "none",
  "users": [
    {
      "id": 1034,
      "inherited": false,
      "permission": "owner"
    },
    {
      "id": 1050,
      "inherited": true,
      "permission": "view"
    }
  ],
  "groups": [
    {
      "id": 5,
      "inherited": false,
      "permission": "edit"
    }
  ]
}

Response fields:

  • editors_can_share (boolean) -- when true, users with edit access can also modify permissions
  • link_permission (string) -- shared link permission level (none, view, or edit)
  • users (array) -- per-user permission overrides
  • id (integer) -- user ID
  • inherited (boolean) -- whether this permission is inherited from the parent folder
  • permission (string) -- permission level
  • groups (array) -- per-group permission overrides
  • id (integer) -- group ID
  • inherited (boolean) -- whether this permission is inherited from the parent folder
  • permission (string) -- permission level

Tip: The access field on the canvas object itself provides a quick way to check the requesting user's effective permission without calling this endpoint.

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 404 Not Found -- canvas does not exist

Set canvas permissions

Updates the permission configuration for a canvas. Only the settings included in the request body are changed; anything omitted keeps its current value. You can set per-user permissions, per-group permissions, shared link access, and whether editors can share.

POST /api/v1/canvases/:canvas_id/permissions
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Request body (JSON):

  • editors_can_share (boolean, optional) -- whether users with edit access can change permissions
  • link_permission (string, optional) -- shared link permission: none, view, or edit
  • users (array, optional) -- per-user permission overrides
  • groups (array, optional) -- per-group permission overrides

Each entry in the users and groups arrays is an object with:

  • id (integer, required) -- the user or group ID
  • permission (string, required) -- one of none, view, edit, or owner, or removed to delete the existing override for that user or group

Link permission values:

  • none -- canvas is not shared via link
  • view -- anyone with the link can view (read-only)
  • edit -- anyone with the link can edit

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "editors_can_share": false,
    "link_permission": "view",
    "users": [{"id": 1050, "permission": "edit"}],
    "groups": [{"id": 5, "permission": "view"}]
  }' \
  https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/permissions

Response: 200 OK

{
  "editors_can_share": false,
  "link_permission": "view",
  "users": [
    {
      "id": 1034,
      "inherited": false,
      "permission": "owner"
    },
    {
      "id": 1050,
      "inherited": false,
      "permission": "edit"
    }
  ],
  "groups": [
    {
      "id": 5,
      "inherited": false,
      "permission": "view"
    }
  ]
}

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions (must be owner or editor with sharing enabled)
  • 404 Not Found -- canvas does not exist

Current behavior

When every requested change fails, including because the caller lacks permission or the canvas does not exist, the server currently returns 400 Bad Request rather than 403 or 404. This is being corrected.

Shared links allow unauthenticated access to a canvas. The link format is:

https://canvus.example.com/open/<canvas-id>

To enable a shared link, set link_permission to view or edit using the Set Canvas Permissions endpoint. To revoke a shared link, set link_permission back to none.

When a shared link is active:

  • API requests for that canvas can omit the Private-Token header, except the move, copy, save, restore, and permissions endpoints
  • Unauthenticated access is granted as the Guest user with the link's permission level
  • If the Guest user account is blocked on the server, shared link access is denied
  • If a valid token is provided, the user gets whichever permission is higher: their own or the link permission

Color presets

Color presets define the palette of colors available in the canvas UI for annotations (inking), note backgrounds, note text, and connectors. Each canvas has its own set of presets.

Get color presets

Returns the color presets configured for a canvas.

GET /api/v1/canvases/:canvas_id/color-presets
  • Authentication: Required (unless canvas has a shared link)
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/color-presets

Response: 200 OK

{
  "annotation": ["#00338dff", "#005eb8ff", "#0091daff", "#470a68ff", "#6d2077ff", "#00a3a1ff"],
  "connector": ["#00338dff", "#005eb8ff", "#0091daff", "#470a68ff", "#6d2077ff", "#00a3a1ff"],
  "note_background": ["#00338dff", "#005eb8ff", "#0091daff", "#470a68ff", "#6d2077ff", "#00a3a1ff"],
  "note_text": []
}

Response fields:

  • annotation (array of strings) -- hex color values for annotation/inking tools
  • connector (array of strings) -- hex color values for connector lines
  • note_background (array of strings) -- hex color values for note backgrounds
  • note_text (array of strings) -- hex color values for note text

Colors use the format #RRGGBB or #RRGGBBAA (with alpha).

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 404 Not Found -- canvas does not exist

Update color presets

Updates one or more color preset categories. Only the categories included in the request body are modified; omitted categories are left unchanged. The connector palette always mirrors the annotation palette: sending annotation updates both.

PATCH /api/v1/canvases/:canvas_id/color-presets
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Request body (JSON):

  • annotation (array of strings, optional) -- inking color palette
  • note_background (array of strings, optional) -- note background color palette
  • note_text (array of strings, optional) -- note text color palette

curl example:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "note_background": ["#ff6b6bff", "#4ecdc4ff", "#45b7d1ff", "#96e6a1ff"],
    "annotation": ["#2d3436ff", "#636e72ff", "#b2bec3ff"]
  }' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/color-presets

Response: 200 OK -- returns the full color presets object with all categories.

{
  "annotation": ["#2d3436ff", "#636e72ff", "#b2bec3ff"],
  "connector": ["#2d3436ff", "#636e72ff", "#b2bec3ff"],
  "note_background": ["#ff6b6bff", "#4ecdc4ff", "#45b7d1ff", "#96e6a1ff"],
  "note_text": []
}

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist

Canvas background

The canvas background can be a solid color, an animated haze, or an uploaded image. An optional grid overlay can be enabled with any background type.

Get canvas background

Returns the current background configuration.

GET /api/v1/canvases/:canvas_id/background
  • Authentication: Required (unless canvas has a shared link)
  • Streaming: Supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/background

Response: 200 OK

{
  "type": "haze",
  "haze": {
    "color1": "#e0e0e0",
    "color2": "#f0f0f0",
    "speed": 0.5,
    "scale": 1.0
  },
  "grid": {
    "visible": true,
    "color": "#cccccc"
  },
  "image": {
    "hash": "",
    "fit": "fill"
  }
}

Response fields:

  • type (string) -- background type: solid_color, haze, or image
  • background_color (string) -- hex color, used when type is solid_color
  • haze (object) -- haze animation settings
  • color1 (string) -- first gradient color
  • color2 (string) -- second gradient color
  • speed (number) -- animation speed
  • scale (number) -- pattern scale
  • grid (object) -- grid overlay settings
  • visible (boolean) -- whether the grid is shown
  • color (string) -- grid line color
  • image (object) -- background image settings
  • hash (string) -- asset hash of the uploaded image
  • fit (string) -- how the image fills the canvas (e.g., fill)

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 404 Not Found -- canvas does not exist

Update canvas background

Changes background settings such as type, color, haze parameters, or grid visibility.

PATCH /api/v1/canvases/:canvas_id/background
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Request body (JSON):

  • type (string, optional) -- solid_color, haze, or image
  • background_color (string, optional) -- hex color for solid backgrounds
  • haze (object, optional) -- haze settings (when type is haze)
  • grid (object, optional) -- grid overlay settings

curl example -- set solid color:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "solid_color", "background_color": "#1a1a2e"}' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/background

curl example -- set haze with grid:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "haze",
    "haze": {"color1": "#0f0c29", "color2": "#302b63", "speed": 0.3, "scale": 1.5},
    "grid": {"visible": true, "color": "#ffffff22"}
  }' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/background

Response: 200 OK -- returns the full background configuration.

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist

Upload background image

Uploads an image file to use as the canvas background. This is a multipart request.

POST /api/v1/canvases/:canvas_id/background
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID

Request body (multipart/form-data):

  • data (file, required) -- the image file to upload
  • json (string, optional) -- JSON string with additional parameters such as fit

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -F "data=@background.jpg" \
  -F 'json={"type": "image", "fit": "fill"}' \
  https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/background

Response: 200 OK -- returns the updated background configuration.

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist

Demo canvas operations

Demo mode allows saving a snapshot of a canvas and restoring it later. This is useful for trade show demos, training sessions, or any scenario where you want to return a canvas to a known state after users have interacted with it.

To enable demo mode, set the canvas mode to demo using the Update a Canvas endpoint.

Save demo state

Captures the current state of a demo canvas as a snapshot. This overwrites any previously saved state.

POST /api/v1/canvases/:canvas_id/save
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID (must be a demo canvas)

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/save

Response: 200 OK (empty body)

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist

Restore demo state

Restores a demo canvas to its last saved state. All changes made since the last save are discarded.

POST /api/v1/canvases/:canvas_id/restore
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • canvas-id (uuid, required) -- the canvas ID (must be a demo canvas)

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/restore

Response: 200 OK (empty body)

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- canvas does not exist