Tables API

New in the latest API version. Table widgets were added as part of the Canvus 3.5 API refactor.

Tables are grid-based container widgets on the canvas. Each table is a structured grid of cells where you can organize content into rows and columns. Use them for comparison matrices, status boards, data summaries, or any layout that benefits from a tabular structure.

A table widget manages its own grid of child cells. When you create a table, the server automatically creates the cell widgets to fill the grid. You interact with the table itself (resize, move, rename) and can read the individual cells through a dedicated cells endpoint.

Every table shares these properties with other canvas widget types:

id (string, uuid) -- Unique identifier assigned by the server. Read-only.
location (object) -- Position on the canvas as {"x": float, "y": float}. Coordinates are relative to the table's parent widget.
size (object) -- Dimensions as {"width": float, "height": float}. If omitted on creation, the server uses a default table size.
depth (number, float) -- Z-order relative to sibling widgets. Higher values render on top. Must be >= 1.0.
scale (number, float) -- Scale factor. Default is 1.
pinned (boolean) -- When true, the table cannot be moved or resized through the touch UI. API writes are unaffected.
state (string) -- Widget state. Typically "normal".
parent_id (string, uuid) -- ID of the parent widget or canvas root. Read-only in responses.
widget_type (string) -- Always "Table" for this resource. Read-only.

Table-Specific Properties

title (string) -- Display title for the table. Patchable.
grid_size (object) -- Grid dimensions as {"columns": integer, "rows": integer}. Set at creation time. Both values must be >= 1. Defaults to {"columns": 2, "rows": 2} if omitted.
column_widths (array of floats) -- Width of each column. Read-only.
row_heights (array of floats) -- Height of each row. Read-only.

Table Cell Properties

Each cell in the grid is a separate widget accessible via the cells endpoint. Cell properties include:

id (string, uuid) -- Unique identifier for the cell. Read-only.
column (number, integer) -- Zero-based column index of the cell. Read-only.
row (number, integer) -- Zero-based row index of the cell. Read-only.
Common widget properties (location, size, depth, scale, pinned, state, parent_id, widget_type)

Auto-Raise

All PATCH requests accept an optional auto_raise boolean parameter (default false). When set to true, the table's depth is automatically set above all siblings.

List Tables

Returns all tables on the specified canvas.

GET /api/v1/canvases/:canvas_id/tables

Path parameters:

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

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates. See Streaming.

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables

Example response:

[
  {
    "depth": 5,
    "grid_size": {
      "columns": 3,
      "rows": 4
    },
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "location": {
      "x": 2000,
      "y": 1500
    },
    "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 600,
      "width": 900
    },
    "state": "normal",
    "title": "Q1 Status Board",
    "widget_type": "Table"
  }
]

Get Single Table

Returns a single table by ID.

GET /api/v1/canvases/:canvas_id/tables/:table_id

Path parameters:

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

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Example response:

{
  "depth": 5,
  "grid_size": {
    "columns": 3,
    "rows": 4
  },
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location": {
    "x": 2000,
    "y": 1500
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 600,
    "width": 900
  },
  "state": "normal",
  "title": "Q1 Status Board",
  "widget_type": "Table"
}

List Table Cells

Returns all cells belonging to tables on the canvas. Each cell includes its row and column position within its parent table.

GET /api/v1/canvases/:canvas_id/tables/:table_id/cells

Path parameters:

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

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cells

Example response:

[
  {
    "column": 0,
    "depth": 1,
    "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "location": {
      "x": 0,
      "y": 0
    },
    "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "pinned": false,
    "row": 0,
    "scale": 1,
    "size": {
      "height": 150,
      "width": 300
    },
    "state": "normal",
    "widget_type": "TableCell"
  },
  {
    "column": 1,
    "depth": 1,
    "id": "d2e3f4a5-b6c7-8901-def0-23456789abcd",
    "location": {
      "x": 300,
      "y": 0
    },
    "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "pinned": false,
    "row": 0,
    "scale": 1,
    "size": {
      "height": 150,
      "width": 300
    },
    "state": "normal",
    "widget_type": "TableCell"
  }
]

Create Table

Creates a new table on the canvas. The server automatically creates the grid cells based on the specified grid_size.

POST /api/v1/canvases/:canvas_id/tables

Path parameters:

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

Body parameters (JSON):

title (string, optional) -- Display title for the table.
grid_size (object, optional) -- Grid dimensions as {"columns": integer, "rows": integer}. Both must be >= 1. Defaults to {"columns": 2, "rows": 2}.
location (object, optional) -- Position as {"x": float, "y": float}.
size (object, optional) -- Dimensions as {"width": float, "height": float}. Uses server default if omitted.
depth (number, optional) -- Z-order. Must be >= 1.0.
scale (number, optional) -- Scale factor.
pinned (boolean, optional) -- Whether the table is pinned in the UI.

Example request:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Feature Comparison",
    "grid_size": {"columns": 4, "rows": 3},
    "location": {"x": 3000, "y": 2000},
    "size": {"width": 1200, "height": 450}
  }' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables

Example response:

{
  "depth": 1,
  "grid_size": {
    "columns": 4,
    "rows": 3
  },
  "id": "f4e3d2c1-b0a9-8765-4321-fedcba098765",
  "location": {
    "x": 3000,
    "y": 2000
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 450,
    "width": 1200
  },
  "state": "normal",
  "title": "Feature Comparison",
  "widget_type": "Table"
}

Update Table

Updates one or more properties of an existing table. Only include the fields you want to change. The grid_size cannot be changed after creation.

PATCH /api/v1/canvases/:canvas_id/tables/:table_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
table_id (uuid, required) -- ID of the table to update

Body parameters (JSON):

title (string, optional) -- New display title.
location (object, optional) -- New position.
size (object, optional) -- New dimensions.
depth (number, optional) -- New z-order. Must be >= 1.0.
scale (number, optional) -- New scale factor.
pinned (boolean, optional) -- New pinned state.
auto_raise (boolean, optional) -- When true, depth is set above all siblings.

Example request:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Comparison Matrix", "pinned": true}' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Example response:

{
  "depth": 5,
  "grid_size": {
    "columns": 3,
    "rows": 4
  },
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location": {
    "x": 2000,
    "y": 1500
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": true,
  "scale": 1,
  "size": {
    "height": 600,
    "width": 900
  },
  "state": "normal",
  "title": "Updated Comparison Matrix",
  "widget_type": "Table"
}

Delete Table

Permanently removes a table and all its cells from the canvas. Any connectors attached to the table are also deleted.

DELETE /api/v1/canvases/:canvas_id/tables/:table_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
table_id (uuid, required) -- ID of the table to delete

Example request:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables/a1b2c3d4-e5f6-7890-abcd-ef1234567890

A successful deletion returns an empty response with HTTP status 200.

Streaming

All GET endpoints support the ?subscribe query parameter for real-time updates. See Streaming for details.

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/tables?subscribe"

List All Table Cells on a Canvas

Returns all table cells across all tables on a canvas in a single flat list, without requiring a specific table ID.

GET /api/v1/canvases/:canvas_id/table-cells

Path parameters:

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

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/table-cells

The response is a JSON array of all table cell widgets on the canvas, each including row, column, parent_id (the owning table), and standard widget properties.

Error Cases

400 Bad Request -- Invalid JSON, depth below 1.0, zero/negative size dimensions, or grid_size with columns or rows less than 1.
401 Unauthorized -- Missing or invalid Private-Token header.
403 Forbidden -- View-only users cannot create, update, or delete tables.
404 Not Found -- The canvas ID or table ID does not exist.

Tables API

Common Widget Properties

Table-Specific Properties

Table Cell Properties

Auto-Raise

List Tables

Get Single Table

List Table Cells

Create Table

Update Table

Delete Table

Streaming

List All Table Cells on a Canvas

Error Cases