Skip to content

Canvus REST API Changelog

v1.4

Targeting Canvus 26.05.x

New Endpoints

  • Annotation CRUD (widget-parented). Full CRUD for freehand stroke annotations attached to a widget at /canvases/{id}/{type}/{widgetId}/annotations (collection) and /canvases/{id}/{type}/{widgetId}/annotations/{annotationId} (item). Methods: POST (create), GET (list and single fetch), PATCH (partial update), DELETE. {type} is one of the mutable widget endpoints: notes, images, browsers, videos, pdfs, anchors, video-inputs, ip-videos, rdp-connections, tables. Serialized properties: id, line_color, depth, page, points. Patchable: points, line_color, page.

  • Annotation CRUD (canvas plane). Whiteboard-style strokes drawn on the canvas itself, not on a widget, use the singleton form at /canvases/{id}/shared-canvas/annotations (collection) and /canvases/{id}/shared-canvas/annotations/{annotationId} (item). No widget ID in the path -- the server resolves the canvas's root node. Same methods and properties as the widget-parented form (minus page, which is PDF-only).

New Parameters

  • points accepts two encodings. Annotation points may be supplied either as a base64-encoded Float32Array (9 floats per node, little-endian: control-in x/y/z, anchor x/y/z, control-out x/y/z) or as a JSON array of 9-float arrays ([[cInX, cInY, cInZ, x, y, z, cOutX, cOutY, cOutZ], ...]). Automation callers can use the JSON form and avoid binary packing.

  • ?points= on GET. Annotation GET (list and single) accepts an optional points query parameter: b64 (default, for backward compatibility) or json to receive points as 9-float-per-node arrays.

New Attributes

  • Annotation line_color -- string, required on create. Hex color with alpha in #RRGGBBAA form (e.g. #ff0000ff).

  • Annotation page -- integer, optional, PDF parents only. Scopes a stroke to a specific PDF page. Sending page on a non-PDF parent returns 400. Must be >= 1. Omitted from responses for non-PDF parents.

  • Annotation depth -- float, server-assigned and read-only. Returned for parity with widget serialization; clients should not set it on create.

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. Cross-canvas widget cloning is now live. POST to the typed endpoint (e.g. /canvases/{id}/notes) with source_canvas_id and source_widget_id in the body to copy a widget from any accessible canvas. Supported types: Note, Image, Browser, Video, PDF, Anchor, Table. An optional location override sets the placement position.

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.

  • Note clone with auto text color. Cloning a Note whose text color was set to automatic (auto_text_color: true) previously failed with "Can't set color when text color selection is automatic". Fixed: the clone path now drops the resolved text_color value when auto_text_color is true, letting the server recompute it on the destination canvas.

  • 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.