Skip to content

Clients

A client in Canvus represents a physical Canvus application instance connected to the server. Each client typically corresponds to a MultiTaction display, a wall of displays, or a desktop running the Canvus application. Clients report their name, software version, and connection state to the server.

The Clients API is read-only. You cannot create or delete clients through the API -- they appear and disappear as Canvus applications connect to and disconnect from the server.

When you would use this API:

  • Discovering which physical displays are online and available
  • Getting the client ID needed to work with workspaces, video inputs, and video outputs
  • Monitoring the connection state of your Canvus deployment
  • Building a dashboard that shows the status of all connected displays

Important: Clients do not expose themselves for API access by default. API access must be enabled on each Canvus client application individually through its local settings.

Authentication

All Clients 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 Clients

Returns all Canvus client applications currently connected to the server.

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

Path parameters: None

Query parameters:

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

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/clients

Example response (200 OK):

[
  {
    "access": "rw",
    "id": "e5cad8d4-7051-4051-97bc-13e41fd81ca7",
    "installation_name": "conference-room-wall",
    "state": "normal",
    "version": "3.4.12 [a1b2c3d4e]"
  },
  {
    "access": "rw",
    "id": "b29f6a13-8820-42e5-9f3a-df1eab7c50a2",
    "installation_name": "lobby-display",
    "state": "normal",
    "version": "3.4.12 [a1b2c3d4e]"
  }
]

Response fields:

  • id (string) -- Unique identifier for the client. Use this ID in all client-scoped API calls (workspaces, video inputs, video outputs).
  • installation_name (string) -- The hostname or human-readable name assigned to the machine running the Canvus client
  • access (string) -- API access level. "rw" indicates read-write access is enabled.
  • state (string) -- Current client state. "normal" indicates the client is operating normally.
  • version (string) -- Canvus software version and build hash running on this client

Get a Single Client

Returns details for one specific client.

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

Path parameters:

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

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

Example response (200 OK):

{
  "access": "rw",
  "id": "e5cad8d4-7051-4051-97bc-13e41fd81ca7",
  "installation_name": "conference-room-wall",
  "state": "normal",
  "version": "3.4.12 [a1b2c3d4e]"
}

Error Responses

  • 401 Unauthorized -- Missing or invalid Private-Token
  • 404 Not Found -- The specified client ID does not exist or the client is no longer connected

All errors return a JSON body:

{
  "msg": "error description"
}

What to Do Next

Once you have a client ID, you can:

  • List and control its workspaces -- the display areas showing canvases
  • Enumerate its video inputs -- hardware capture devices attached to the client
  • Enumerate and configure its video outputs -- display outputs from the client