Skip to content

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.

Common Widget Properties

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. Read-only in responses.
  • 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.

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 (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/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 (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/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, optional) -- Stream URL (RTSP, RTMP, or other network video URI).
  • 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 '{
    "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.
  • 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.

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.

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"

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

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.