Widgets (Generic)

The generic widgets endpoint provides a unified, read-only view of every item on a canvas regardless of its type. A single request returns all notes, images, videos, PDFs, browsers, anchors, video inputs, connectors, and every other widget type in one list.

Each widget in the response includes a widget_type field that tells you what kind of content it represents. The fields returned vary by type -- an image widget includes hash and original_filename, while a note widget includes text and background_color.

When you would use this API:

Getting a complete inventory of everything on a canvas in a single call
Building a canvas viewer or dashboard that needs to display all content types
Searching across all widget types (e.g., finding all items at a specific location)
Monitoring canvas changes with ?subscribe for real-time updates across all types
Reading widget properties when you do not know the type in advance

When to use type-specific endpoints instead:

If you need to create, update, or delete widgets, use the type-specific endpoints (e.g., /canvases/:id/notes, /canvases/:id/images). The generic widgets endpoint is primarily for reading.

Authentication

The GET endpoints require authentication via the Private-Token header, unless the canvas has link sharing enabled (View or Edit permission), in which case no authentication is needed.

Private-Token: YOUR_TOKEN

Streaming

All GET endpoints support the ?subscribe query parameter for long-poll streaming. When present, the server holds the connection open and sends newline-delimited JSON updates whenever any widget on the canvas changes. See the API overview for details.

The widget_type field identifies the kind of widget. Possible values:

"Note" -- A sticky note with text content
"Image" -- An uploaded image file
"Video" -- An uploaded video file
"PDF" -- An uploaded PDF document
"Browser" -- An embedded web browser
"Anchor" -- A named anchor point on the canvas
"VideoInput" -- A live video capture feed from a hardware device
"IpVideo" -- A network video stream (RTSP, etc.)
"RdpConnection" -- A remote desktop connection
"Connector" -- A line connecting two widgets
"Table" -- A grid-based table widget
"TableCell" -- A cell within a Table widget grid
"SharedCanvas" -- The root canvas container widget. Not directly modifiable via the API.
"VideoOutputAnchor" -- A region defining video output bounds
"CanvasBackground" -- The canvas background widget

All widget types share a base set of fields:

id (string) -- Unique identifier for the widget
widget_type (string) -- The type of widget (see list above)
location (object) -- Position on the canvas as {"x": ..., "y": ...}
depth (number) -- Z-order value. Higher values render on top of lower values.
parent_id (string) -- ID of the parent widget (typically the SharedCanvas root)
state (string) -- Current widget state (e.g., "normal")

Most widget types also include:

size (object) -- Width and height as {"width": ..., "height": ...}
scale (number) -- Display scale factor
pinned (boolean) -- Whether the widget is pinned in place

Asset-based widgets (Image, Video, PDF) additionally include:

hash (string) -- Content hash for the uploaded file. Used with the mipmaps and assets endpoints.
original_filename (string) -- The filename of the uploaded file
title (string) -- Display title

List All Widgets on a Canvas

Returns every widget on the specified canvas.

Method: GET
URL: /api/v1/canvases/:canvas_id/widgets
Authentication: Required (unless canvas has link sharing)
Streaming: Supported via ?subscribe

Path parameters:

canvas_id (uuid, required) -- ID of the canvas

Query parameters:

subscribe (boolean, optional) -- Enable long-poll streaming

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/3ad9ece4-28be-4e19-9f9a-1a01a4dbae28/widgets

Example response (200 OK):

[
  {
    "depth": 0,
    "id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "location": {
      "x": 0,
      "y": 0
    },
    "parent_id": "",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 5400,
      "width": 9600
    },
    "state": "normal",
    "widget_type": "SharedCanvas"
  },
  {
    "depth": 0,
    "hash": "cbcb439a796b",
    "id": "2a59b935-02b6-47dc-820c-caab1de64247",
    "location": {
      "x": 5291.9,
      "y": 2564.2
    },
    "original_filename": "photo.jpg",
    "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 100,
      "width": 100
    },
    "state": "normal",
    "title": "A dog",
    "widget_type": "Image"
  },
  {
    "background_color": "#ffffff",
    "depth": 0,
    "id": "dc3ca5b6-0fb4-4628-bf4e-2008087b9430",
    "location": {
      "x": 5997.6,
      "y": 3253.6
    },
    "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 300,
      "width": 300
    },
    "state": "normal",
    "text": "Remember to review the Q3 numbers",
    "widget_type": "Note"
  },
  {
    "anchor_index": 0,
    "anchor_name": "Overview",
    "depth": 0,
    "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
    "location": {
      "x": 4676.8,
      "y": 2432.8
    },
    "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 800,
      "width": 1200
    },
    "state": "normal",
    "widget_type": "Anchor"
  }
]

Returns a single widget by ID. The widget can be of any type.

Method: GET
URL: /api/v1/canvases/:canvas_id/widgets/:widget_id
Authentication: Required (unless canvas has link sharing)
Streaming: Supported via ?subscribe

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
widget_id (uuid, required) -- ID of the widget

Query parameters:

subscribe (boolean, optional) -- Enable long-poll streaming

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/3ad9ece4-28be-4e19-9f9a-1a01a4dbae28/widgets/2a59b935-02b6-47dc-820c-caab1de64247

Example response (200 OK):

{
  "depth": 0,
  "hash": "cbcb439a796b",
  "id": "2a59b935-02b6-47dc-820c-caab1de64247",
  "location": {
    "x": 5291.9,
    "y": 2564.2
  },
  "original_filename": "photo.jpg",
  "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A dog",
  "widget_type": "Image"
}

Clone Widgets (Not Implemented)

This endpoint is reserved for cross-canvas widget cloning but is not yet implemented.

Method: POST
URL: /api/v1/canvases/:canvas_id/widgets/clone
Status: Returns 501 Not Implemented

Calling this endpoint will return:

{
  "msg": "Not Implemented"
}

Error Responses

401 Unauthorized -- Missing or invalid Private-Token (and canvas does not have link sharing)
404 Not Found -- The specified canvas or widget does not exist

All errors return a JSON body:

{
  "msg": "error description"
}

Widgets (Generic)

Authentication

Streaming

Widget Types

Common Widget Fields

List All Widgets on a Canvas

Get a Single Widget

Clone Widgets (Not Implemented)

Error Responses