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. The request must also include a non-empty host-id identifying the client that owns the device; without it the server returns 400 Bad Request.

Authentication

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

Private-Token: YOUR_TOKEN

Streaming

Streaming is not supported for video inputs. A request that includes ?subscribe returns an error instead of holding the connection open. Poll the GET endpoints to detect changes.

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: Not supported

Path parameters:

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

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": "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"
  },
  {
    "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"
  }
]

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: Not supported

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • input_id (integer, required) -- Zero-based position of the device in the list returned by List all video inputs for a client. Devices have no separate ID. The list is sorted by source, so positions can change when devices are connected or removed.

Example request:

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

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

  • 400 Bad Request -- input_id is not a non-negative integer
  • 401 Unauthorized -- Missing or invalid Private-Token
  • 404 Not Found -- The specified client or video input does not exist

Current behavior

  • An invalid or expired token returns 403 Forbidden, not 401. See Current behavior.
  • An input_id past the end of the device list returns 400 Bad Request ("Input id is not integer") instead of 404 Not Found.

These are being corrected.

All errors return a JSON body:

{
  "msg": "error description"
}