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.

Authentication

All endpoints require authentication via the Private-Token header or a CanvusSession cookie, unless the canvas has link sharing enabled (View or Edit permission). Write operations (POST, PATCH, DELETE) require edit access. View-only users receive 403 Forbidden on any write attempt.

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. Can be set on creation and changed with PATCH. Defaults to the canvas root.
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 and cannot be changed afterward. Values below 1 are raised to 1. Defaults to {"columns": 2, "rows": 2} if omitted.

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.

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 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 (flag, optional) -- Enable streaming updates. The parameter takes no value; its presence alone turns streaming on, so ?subscribe=false also streams. 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 (flag, optional) -- Enable streaming updates. The parameter takes no value; its presence alone turns streaming on, so ?subscribe=false also streams.

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}. Values below 1 are raised to 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.
parent_id (uuid, optional) -- ID of the parent widget. Defaults to the canvas root.

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.
parent_id (uuid, optional) -- Move the table under another widget. Send location as well, because coordinates are relative to the parent.

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.

Current behavior

Deleting a widget does not yet delete the connectors attached to it. The server removes them later, the next time the canvas is loaded; until then they are still returned. Delete them yourself if you need them gone immediately. This is being corrected.

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.

Error responses

400 Bad Request -- Invalid JSON, depth below 1.0, or zero/negative size dimensions.
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.

Current behavior

An invalid or expired token returns 403 Forbidden, not 401. See Current behavior.
Create does not yet enforce the depth limit. A widget created without depth gets 0, and a value below 1.0 is accepted. Only update rejects it.
A zero or negative size is not rejected. Create stores it; update ignores it and still returns 200 OK.
An update rejected with 400 Bad Request can still apply other fields sent in the same request.

These are being corrected.

Tables API

Authentication

Common widget properties

Table-specific properties

Table cell properties

Auto-raise

Streaming

List tables

Get single table

List table cells

Create table

Update table

Delete table

Error responses