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.

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. Read-only in responses.
widget_type (string) -- Always "RdpConnection" for this resource. Read-only.

RDP-Specific Properties

connection_name (string) -- The hostname or IP address of the remote machine to connect to. 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) -- Internal content identifier. Empty until a Canvus client connects and establishes the RDP session. 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.

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

Example response:

[
  {
    "connection_name": "workstation-04.corp.example.com",
    "content_id": "rdp-session-a1b2c3",
    "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 (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/rdp-connections/d4c3b2a1-0987-6543-21fe-dcba09876543

Example response:

{
  "connection_name": "workstation-04.corp.example.com",
  "content_id": "rdp-session-a1b2c3",
  "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, optional) -- Hostname or IP address of the remote machine.
title (string, optional) -- Display title for the widget.
location (object, optional) -- Position as {"x": float, "y": float}.
size (object, optional) -- Dimensions as {"width": float, "height": float}.
depth (number, optional) -- Z-order. Must be >= 1.0.
scale (number, optional) -- Scale factor.
pinned (boolean, optional) -- Whether the widget is pinned in the UI.

Example request:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_name": "demo-server.corp.example.com",
    "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.corp.example.com",
  "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 hostname or IP address.
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": "Production Server", "connection_name": "prod-01.corp.example.com"}' \
  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.corp.example.com",
  "content_id": "rdp-session-a1b2c3",
  "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.

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.

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"

Error Cases

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 RDP Connection widgets.
404 Not Found -- The canvas ID or widget ID does not exist.

Notes on RDP Behavior

The connection_name is the hostname or IP address the Canvus desktop client uses to establish the RDP session. The remote machine must be network-reachable from the client, not from the server.
RDP authentication is handled by the Canvus desktop client at connection time. 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 an internal identifier for the RDP session content. It is assigned by the system and is read-only.
RDP support requires a Canvus desktop client with RDP capability enabled. The feature uses FreeRDP on Linux clients.

RDP Connections API

Common Widget Properties

RDP-Specific Properties

Auto-Raise

List RDP Connections

Get Single RDP Connection

Create RDP Connection

Update RDP Connection

Delete RDP Connection

Streaming

Error Cases

Notes on RDP Behavior