IP videos API

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

IP Video widgets embed live network video streams on the canvas. They display content from IP cameras, RTSP/RTMP streams, or any other network video source accessible from the Canvus client. Use them to build surveillance dashboards, embed live event feeds into collaboration spaces, or display real-time video from manufacturing floor cameras alongside related data.

The stream URL points to the video source. The Canvus desktop client handles decoding and rendering -- the server stores the widget's metadata and stream configuration, but does not transcode or relay the video data itself.

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 IP Video 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 "IpVideo" for this resource. Read-only.

IP video-specific properties

source (string) -- The stream URL (e.g., an RTSP or RTMP address). Patchable.
title (string) -- Display title for the widget. Patchable.
host-id (string) -- Identifier of the Canvus client host that owns this stream. 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/ip-videos?subscribe"

List IP videos

Returns all IP Video widgets on the specified canvas.

GET /api/v1/canvases/:canvas_id/ip-videos

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/ip-videos

Example response:

[
  {
    "depth": 4,
    "host-id": "client-7f3a2b",
    "id": "e1f2a3b4-c5d6-7890-ef01-234567890abc",
    "location": {
      "x": 500,
      "y": 300
    },
    "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 720,
      "width": 1280
    },
    "source": "rtsp://192.168.1.100:554/stream1",
    "state": "normal",
    "title": "Lobby Camera",
    "widget_type": "IpVideo"
  }
]

Get single IP video

Returns a single IP Video widget by ID.

GET /api/v1/canvases/:canvas_id/ip-videos/:widget_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
widget_id (uuid, required) -- ID of the IP Video 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/ip-videos/e1f2a3b4-c5d6-7890-ef01-234567890abc

Example response:

{
  "depth": 4,
  "host-id": "client-7f3a2b",
  "id": "e1f2a3b4-c5d6-7890-ef01-234567890abc",
  "location": {
    "x": 500,
    "y": 300
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 720,
    "width": 1280
  },
  "source": "rtsp://192.168.1.100:554/stream1",
  "state": "normal",
  "title": "Lobby Camera",
  "widget_type": "IpVideo"
}

Create IP video

Creates a new IP Video widget on the canvas.

POST /api/v1/canvases/:canvas_id/ip-videos

Path parameters:

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

Body parameters (JSON):

source (string, required) -- Stream URL (RTSP, RTMP, or other network video URI). Empty value returns 400 Bad Request.
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": 800, "height": 450}.
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 '{
    "source": "rtsp://192.168.1.50:554/live/parking-lot",
    "title": "Parking Lot Camera",
    "location": {"x": 2000, "y": 1000},
    "size": {"width": 1280, "height": 720}
  }' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/ip-videos

Example response:

{
  "depth": 1,
  "host-id": "",
  "id": "f5e4d3c2-b1a0-9876-5432-10fedcba9876",
  "location": {
    "x": 2000,
    "y": 1000
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 720,
    "width": 1280
  },
  "source": "rtsp://192.168.1.50:554/live/parking-lot",
  "state": "normal",
  "title": "Parking Lot Camera",
  "widget_type": "IpVideo"
}

Update IP video

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

PATCH /api/v1/canvases/:canvas_id/ip-videos/:widget_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
widget_id (uuid, required) -- ID of the IP Video widget to update

Body parameters (JSON):

source (string, optional) -- New stream URL.
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": "Front Entrance Camera", "source": "rtsp://192.168.1.51:554/stream1"}' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/ip-videos/e1f2a3b4-c5d6-7890-ef01-234567890abc

Example response:

{
  "depth": 4,
  "host-id": "client-7f3a2b",
  "id": "e1f2a3b4-c5d6-7890-ef01-234567890abc",
  "location": {
    "x": 500,
    "y": 300
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 720,
    "width": 1280
  },
  "source": "rtsp://192.168.1.51:554/stream1",
  "state": "normal",
  "title": "Front Entrance Camera",
  "widget_type": "IpVideo"
}

Delete IP video

Permanently removes an IP Video widget from the canvas. 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/ip-videos/:widget_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
widget_id (uuid, required) -- ID of the IP Video 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/ip-videos/e1f2a3b4-c5d6-7890-ef01-234567890abc

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

Error responses

400 Bad Request -- Invalid JSON, empty or missing source, 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 IP Video 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 IP video behavior

The source URL must be reachable from the Canvus desktop client, not the server. The server stores the URL but does not fetch or relay the stream.
The host-id field identifies which connected Canvus client is responsible for decoding the stream. This is set automatically and cannot be changed via the API.
Common stream URL formats include rtsp://host:port/path for RTSP and rtmp://host:port/path for RTMP.

IP videos API

Authentication

Common widget properties

IP video-specific properties

Auto-raise

Streaming

List IP videos

Get single IP video

Create IP video

Update IP video

Delete IP video

Error responses

Notes on IP video behavior