RDP connections API

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

RDP Connection widgets embed live Remote Desktop Protocol sessions on the canvas. They allow Canvus users to interact with remote Windows (or other RDP-capable) machines directly from the collaborative canvas surface. Use them to build control room dashboards, provide shared access to remote workstations during presentations, or embed live application sessions alongside related notes and documents.

The Canvus desktop client handles the RDP connection, rendering, and input forwarding. The server stores the widget's metadata and connection configuration but does not proxy or relay the RDP session traffic.

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 RDP Connection widget 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 widget's parent.
size (object) -- Dimensions as {"width": float, "height": float}.
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 widget 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 create and changed with PATCH to move the widget under a different parent. Omit it to use the canvas root.
widget_type (string) -- Always "RdpConnection" for this resource. Read-only.

RDP-specific properties

connection-name (string) -- The name of an RDP connection entry defined in the Canvus server's ini configuration. This is a named reference, not a hostname or IP address. Patchable.
title (string) -- Display title for the widget on the canvas. Patchable.
host-id (string) -- Identifier of the Canvus client host managing this RDP session. Read-only.
content-id (string) -- When the widget is in remote file handler mode, the ID of the canvas asset it is displaying. Empty otherwise. Read-only.

Auto-raise

All PATCH requests accept an optional auto_raise boolean parameter (default false). When set to true, the widget'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/rdp-connections?subscribe"

List RDP connections

Returns all RDP Connection widgets on the specified canvas.

GET /api/v1/canvases/:canvas_id/rdp-connections

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/rdp-connections

Example response:

[
  {
    "connection-name": "workstation-04",
    "content-id": "",
    "depth": 6,
    "host-id": "client-7f3a2b",
    "id": "d4c3b2a1-0987-6543-21fe-dcba09876543",
    "location": {
      "x": 3500,
      "y": 1200
    },
    "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 900,
      "width": 1600
    },
    "state": "normal",
    "title": "Engineering Workstation",
    "widget_type": "RdpConnection"
  }
]

Get single RDP connection

Returns a single RDP Connection widget by ID.

GET /api/v1/canvases/:canvas_id/rdp-connections/:widget_id

Path parameters:

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

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/rdp-connections/d4c3b2a1-0987-6543-21fe-dcba09876543

Example response:

{
  "connection-name": "workstation-04",
  "content-id": "",
  "depth": 6,
  "host-id": "client-7f3a2b",
  "id": "d4c3b2a1-0987-6543-21fe-dcba09876543",
  "location": {
    "x": 3500,
    "y": 1200
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 900,
    "width": 1600
  },
  "state": "normal",
  "title": "Engineering Workstation",
  "widget_type": "RdpConnection"
}

Create RDP connection

Creates a new RDP Connection widget on the canvas.

POST /api/v1/canvases/:canvas_id/rdp-connections

Path parameters:

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

Body parameters (JSON):

connection-name (string, required) -- Name of an RDP connection entry in the Canvus server ini configuration. Empty value returns 400 Bad Request. Direct connection parameters (URL, username, password) are not supported.
title (string, optional) -- Display title for the widget.
parent_id (string, optional) -- ID of the parent widget. Defaults to the canvas root. Returns 404 Not Found if no such widget exists.
location (object, optional) -- Position as {"x": float, "y": float}. If omitted, the widget is placed near the center of its parent, offset at random by up to one eighth of the parent's width and height.
size (object, optional) -- Dimensions as {"width": float, "height": float}. Default: {"width": 1920, "height": 1080}.
depth (number, optional) -- Z-order. Must be >= 1.0.
scale (number, optional) -- Scale factor. Default: 1.0.
pinned (boolean, optional) -- Whether the widget is pinned in the UI. Default: false.

Example request:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection-name": "demo-server",
    "title": "Demo Server",
    "location": {"x": 1000, "y": 800},
    "size": {"width": 1920, "height": 1080}
  }' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/rdp-connections

Example response:

{
  "connection-name": "demo-server",
  "content-id": "",
  "depth": 1,
  "host-id": "",
  "id": "a9b8c7d6-e5f4-3210-9876-543210fedcba",
  "location": {
    "x": 1000,
    "y": 800
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 1080,
    "width": 1920
  },
  "state": "normal",
  "title": "Demo Server",
  "widget_type": "RdpConnection"
}

Update RDP connection

Updates one or more properties of an existing RDP Connection widget. Only include the fields you want to change.

PATCH /api/v1/canvases/:canvas_id/rdp-connections/:widget_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
widget_id (uuid, required) -- ID of the RDP Connection widget to update

Body parameters (JSON):

connection-name (string, optional) -- New connection name. Like on create, this is the name of an RDP connection entry, not a hostname or IP address.
title (string, optional) -- New display title.
parent_id (string, optional) -- ID of the new parent widget. Send it together with location, because coordinates are relative to the parent.
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": "Production Server", "connection-name": "prod-01"}' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/rdp-connections/d4c3b2a1-0987-6543-21fe-dcba09876543

Example response:

{
  "connection-name": "prod-01",
  "content-id": "",
  "depth": 6,
  "host-id": "client-7f3a2b",
  "id": "d4c3b2a1-0987-6543-21fe-dcba09876543",
  "location": {
    "x": 3500,
    "y": 1200
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 900,
    "width": 1600
  },
  "state": "normal",
  "title": "Production Server",
  "widget_type": "RdpConnection"
}

Delete RDP connection

Permanently removes an RDP Connection widget from the canvas. The remote desktop session (if active) is terminated. Any connectors attached to this widget 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/rdp-connections/:widget_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
widget_id (uuid, required) -- ID of the RDP Connection widget to delete

Example request:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/rdp-connections/d4c3b2a1-0987-6543-21fe-dcba09876543

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

Error responses

400 Bad Request -- Invalid JSON, empty or missing connection-name, 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 RDP Connection widgets.
404 Not Found -- The canvas ID or widget 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.

Notes on RDP behavior

The connection-name references a named RDP connection entry defined in the Canvus server's ini configuration. It is not a hostname or IP address. The connection entry in the ini file specifies the target machine and any required parameters. Direct connection parameters (URL, username, password) are not supported via the API.
RDP authentication is handled by the Canvus desktop client at connection time using the configuration in the server ini. The API does not store or transmit RDP credentials.
The host-id field identifies which connected Canvus client is managing the RDP session. This is assigned automatically when a client picks up the connection and cannot be changed via the API.
The content-id is set only when the widget is in remote file handler mode, where it holds the ID of the canvas asset being displayed. It is not related to whether an RDP session is established, and it is read-only.
RDP support requires a Canvus desktop client with RDP capability enabled. The feature uses FreeRDP on Linux clients.

RDP connections API

Authentication

Common widget properties

RDP-specific properties

Auto-raise

Streaming

List RDP connections

Get single RDP connection

Create RDP connection

Update RDP connection

Delete RDP connection

Error responses

Notes on RDP behavior