Skip to content

Video Inputs

Video inputs are the hardware video capture devices (webcams, capture cards, HDMI input cards) physically connected to a Canvus client machine. This API lets you enumerate the available capture devices on any connected client.

This is a read-only discovery endpoint. You cannot create, modify, or delete video input devices through the API -- they are detected automatically by the Canvus client from the connected hardware.

When you would use this API:

  • Discovering which capture devices are available on a specific Canvus display
  • Getting the source string needed to create a video input widget on a canvas
  • Building a device inventory of your Canvus deployment

Important: Do not confuse this endpoint with the canvas video input widgets endpoint (/canvases/:id/video-inputs). This endpoint lists hardware devices on a client. The canvas endpoint manages video input widgets that display those device feeds on a canvas.

Workflow for displaying a video feed on a canvas:

  1. Use this endpoint to enumerate available capture devices on a client
  2. Copy the source value from the desired device
  3. Create a video input widget on a canvas using the /canvases/:id/video-inputs endpoint, passing the source value

Authentication

All Video Inputs endpoints require authentication via the Private-Token header.

Private-Token: YOUR_TOKEN

Streaming

All GET endpoints support the ?subscribe query parameter for long-poll streaming. When present, the server holds the connection open and sends newline-delimited JSON updates whenever the data changes. See the API overview for details.

List All Video Inputs for a Client

Returns all video capture devices detected on a specific client.

  • Method: GET
  • URL: /api/v1/clients/:client_id/video-inputs
  • Authentication: Required
  • Streaming: Supported via ?subscribe

Path parameters:

  • client_id (uuid, required) -- ID of the client

Query parameters:

  • subscribe (boolean, optional) -- Enable long-poll streaming

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/video-inputs

Example response (200 OK):

[
  {
    "name": "USB2.0 5M UVC WebCam",
    "resolution": {
      "height": 0,
      "width": 0
    },
    "source": "video=@device_pnp_\\\\?\\usb#vid_3277&pid_0031&mi_00#6&399d7860&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global"
  },
  {
    "name": "Datapath VisionRGB-E1S",
    "resolution": {
      "height": 1080,
      "width": 1920
    },
    "source": "video=@device_pnp_\\\\?\\pci#ven_1254&dev_0001#4&2d41f5e0&0&0008#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global"
  }
]

Response fields:

  • name (string) -- Human-readable name of the capture device
  • resolution (object) -- Reported capture resolution as width and height. May be 0 for both dimensions if the device does not report its resolution.
  • source (string) -- Device identifier string. Use this value as the source field when creating a video input widget on a canvas.

Get a Single Video Input

Returns details for a specific video input device on a client.

  • Method: GET
  • URL: /api/v1/clients/:client_id/video-inputs/:input_id
  • Authentication: Required
  • Streaming: Supported via ?subscribe

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • input_id (string, required) -- ID of the video input device

Query parameters:

  • subscribe (boolean, optional) -- Enable long-poll streaming

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/video-inputs/a3f1b2c4-9876-4def-abcd-1234567890ab

Example response (200 OK):

{
  "name": "USB2.0 5M UVC WebCam",
  "resolution": {
    "height": 0,
    "width": 0
  },
  "source": "video=@device_pnp_\\\\?\\usb#vid_3277&pid_0031&mi_00#6&399d7860&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global"
}

Error Responses

  • 401 Unauthorized -- Missing or invalid Private-Token
  • 404 Not Found -- The specified client or video input does not exist

All errors return a JSON body:

{
  "msg": "error description"
}