Skip to content

Canvus REST API Changelog

v1.3

Targeting Canvus 26.04.x

Breaking Changes

  • Depth validation enforced. PATCH requests that set depth below 1.0 now return 400 Bad Request. Previously, any float was accepted, and values like -1 or 0 made widgets render behind the canvas background, permanently inaccessible from the UI. Migration: update any automation that sets depth below 1.0.

  • View-only users receive 403 on writes. PATCH, POST (create), and DELETE requests from view-only users now return 403 Forbidden. Previously, these returned 200 OK and silently dropped the write. Migration: check for view-only status before issuing writes, or handle 403 responses.

  • PDF index validation. PATCH requests that set PDF index to a negative value now return 400 Bad Request. Index 0 is the first page. Migration: ensure page index values are zero or positive.

  • Image and video resize enforces aspect ratio. PATCH requests that change size on Image or Video widgets now enforce the current aspect ratio. The requested size is treated as a bounding box using longest-edge scaling. The response contains the corrected size values. Migration: read the response body to get the actual applied size.

  • Video pause preserves playback position. When PATCH changes playback_state to "paused" without providing playback_position, the server now computes the correct current position. Previously, pausing without an explicit position caused the video to jump back to where it started playing. Migration: clients that always sent playback_position as a workaround can remove that workaround.

New Widget Types

  • IP Video widgets. Full CRUD at /canvases/{id}/ip-videos. Serialized properties: source, host-id, title. Patchable: title, source.

  • RDP Connection widgets. Full CRUD at /canvases/{id}/rdp-connections. Serialized properties: connection-name, host-id, content-id, title. Patchable: title, connection-name.

  • Table widgets. Full CRUD at /canvases/{id}/tables with cell listing at /canvases/{id}/tables/{tableId}/cells. Creation accepts optional grid_size (default 2x2). Table cells expose column and row fields.

  • VideoOutputAnchor. Now a fully typed widget in API responses with title in both GET serialization and PATCH handling. Type reported as "VideoOutputAnchor".

  • Widget clone endpoint (stub). POST /canvases/{id}/widgets/clone registered. Currently returns 501 Not Implemented. Full server-side cloning planned for a future release.

New Attributes

  • Video muted -- boolean, default false. Readable and patchable via PATCH. Example: {"muted": true}.

  • Video duration -- float, seconds, default 0.0. Read-only (populated by the desktop client's video decoder). Value is 0.0 if the video has not yet been decoded by any client.

New Parameters

  • auto_raise on PATCH. All widget PATCH endpoints accept an optional auto_raise boolean (default false). When true, sets the widget's depth to maxSiblingDepth + 1.0, matching the UI's bring-to-front behavior.

New Endpoints

  • GET /canvases/{id}/uploads-folder -- lists assets uploaded via POST /uploads-folder. Previously, uploaded assets could not be distinguished from canvas-placed items.

Bug Fixes

  • Note title PATCH. PATCH on Notes now accepts the title field. Previously it was serialized in GET and set during creation, but PATCH silently ignored it.

  • VideoInput title. GET on VideoInput widgets now includes title. PATCH on VideoInput now accepts title.

  • TableCell row/column. GET on TableCell widgets now includes column and row fields derived from the cell index. Previously fell through to bare CanvasItem serialization.

  • Note positioning with scale < 1. Fixed coordinate conversion where the 30px padding was added without being multiplied by the widget's scale factor. Notes placed via API at scale < 1 now appear at the correct position.

  • PDF re-render on size change. Changing a PDF widget's size via the API now triggers a re-render at the new dimensions. Previously, the frame updated but the raster stayed at the initial load size.

  • Cross-server canvas open permission denied. Fixed syncUserAndServerInfo() to set the owner attribute for cross-server users, which was causing validateOwner to reject commands.

  • Video output error messages. Replaced generic error message with specific cases: widget not found (404), no canvas open (400), permission denied (403).

  • Reparenting without location warning. When PATCH changes parent_id without location, the server now logs a warning about coordinates being reinterpreted in the new parent's coordinate space.

  • Size validation. PATCH requests with zero or negative width/height are now rejected.

Infrastructure

  • SSE keepalive interval now uses the configured KeepAlive value instead of hardcoded 15 seconds.
  • Docker/Podman network trust is configurable via TrustedProxyNetworks setting (list of CIDRs, default ["172.0.0.0/8"]).
  • TLS cipher suite hardened: removed non-forward-secrecy ciphers, retained only ECDHE suites.
  • HTTP-to-HTTPS redirect changed from 307 Temporary to 308 Permanent.
  • Deprecated Go ioutil APIs replaced with modern equivalents.
  • Error response fallback no longer returns silent {} on JSON marshal failure.

Documentation

  • view_rectangle coordinate system documented: canvas coordinate space, width/scale authoritative, height re-derived from display aspect ratio, SET response returns post-correction values.

v1.2

  • Added unauthenticated access for link-shared canvases and link_permission attribute to the permissions endpoint.
  • Added /uploads-folder endpoint.
  • Added /send-test-email endpoint.
  • Added title parameter for Notes.
  • Filter out the ID of the currently open canvas in the Client API if the user who makes the request doesn't have access to that canvas.
  • Added server_name attribute to the /server-config.

v1.1

  • Removed ini file tokens, made authentication mandatory for most endpoints.
  • Added /login, login/saml and /logout endpoints.
  • Added users and groups management API.
  • Added /permissions endpoints for canvases and folders.
  • Added DELETE /children for folders.
  • Added mode (demo or normal) attribute for canvases.
  • Added /save and /restore endpoints for canvases.
  • Added /preview for canvases.
  • Added API tokens management API.
  • Added license management API.
  • Added audit log API.
  • Added /server-config endpoint.
  • Applied permissions model to the Client API.
  • Added /open-canvas endpoint for workspaces.
  • Added user-email and server-id attributes to the /workspace.

v1.0

  • Initial release of the Canvus REST API.
  • Canvas, note, image, video, PDF, browser, and widget CRUD.
  • Client and workspace read endpoints.
  • File upload and download for media assets.