Skip to content

Video Outputs

Video outputs are the display outputs on a connected Canvus client machine. Each video output represents a physical display channel (such as an HDMI or DisplayPort output) that can show content from a workspace or a VideoOutputAnchor widget on a canvas.

This API lets you list the video outputs on a client and update their configuration, such as changing what content they display or suspending the output.

When you would use this API:

  • Discovering which display outputs are available on a specific Canvus client
  • Changing which workspace or canvas region is shown on a physical output
  • Suspending or resuming a video output programmatically
  • Building projection mapping or multi-display automation

Authentication

All Video Outputs 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 Outputs for a Client

Returns all video outputs for a specific client device.

  • Method: GET
  • URL: /api/v1/clients/:client_id/video-outputs
  • 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/cf8b0fa0-6671-4f68-99df-8e38b010e84b/video-outputs

Example response (200 OK):

[
  {
    "index": 0,
    "label": "Projector",
    "source": "workspace-0",
    "suspended": false
  },
  {
    "index": 1,
    "label": "Secondary Display",
    "source": "workspace-1",
    "suspended": true
  }
]

Response fields:

  • index (number) -- Zero-based index of this video output channel on the client
  • label (string) -- Human-readable label shown in Canvus menus
  • source (string) -- What content this output is displaying. Possible values:
    • "workspace-N" -- Showing the content of workspace at index N (e.g., "workspace-0")
    • A UUID string -- Showing the view from a VideoOutputAnchor widget on the canvas
  • suspended (boolean) -- Whether the output is suspended. false means actively displaying content; true means output is paused.

Get a Single Video Output

Returns details for a specific video output on a client.

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

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • output_index (number, required) -- Zero-based index of the video output

Query parameters:

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

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/clients/cf8b0fa0-6671-4f68-99df-8e38b010e84b/video-outputs/0

Example response (200 OK):

{
  "index": 0,
  "label": "Projector",
  "source": "workspace-0",
  "suspended": false
}

Update a Video Output

Changes the source or suspension state of a video output.

  • Method: PATCH
  • URL: /api/v1/clients/:client_id/video-outputs/:output_index
  • Authentication: Required
  • Streaming: Not applicable

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • output_index (number, required) -- Zero-based index of the video output

Request body fields (all optional):

  • source (string) -- Change what the output displays. Set to "workspace-N" for a workspace view, or to a VideoOutputAnchor widget ID for a canvas region.
  • suspended (boolean) -- Set to true to suspend the output, false to resume it

Example request -- suspend an output:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"suspended": true}' \
  https://canvus.example.com/api/v1/clients/cf8b0fa0-6671-4f68-99df-8e38b010e84b/video-outputs/0

Example request -- switch output to workspace 1:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "workspace-1"}' \
  https://canvus.example.com/api/v1/clients/cf8b0fa0-6671-4f68-99df-8e38b010e84b/video-outputs/0

Example response (200 OK):

Returns the full video output object with updated values.

{
  "index": 0,
  "label": "Projector",
  "source": "workspace-1",
  "suspended": false
}

Known limitation: Changing the source to a VideoOutputAnchor widget ID via the API may not work reliably in all versions. As a workaround, set the projection source through the Canvus UI first, then use the API to suspend and resume the output.

VideoOutputAnchor Widgets

A VideoOutputAnchor is a special widget on a canvas that defines a region for video output. When a video output's source is set to the ID of a VideoOutputAnchor widget, the output displays the canvas content within that widget's bounds.

VideoOutputAnchor widgets appear in the generic widgets listing with "widget_type": "VideoOutputAnchor". They are currently created through the Canvus UI, not through the API.

Error Responses

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

All errors return a JSON body:

{
  "msg": "error description"
}