Skip to content

Canvus API

The Canvus API is a RESTful API on the Canvus server that enables automation and manipulation of content in Canvus by developers.

See the developer guide for how to use the API.

The API can be used to control Canvus clients that connect to an Canvus server which has enabled the API. By default, the client does not expose its state to the server. You can configure the client to disable API access, allow read-only access, or allow read/write access. Check the below section for more info.

What the API can do with a client

Canvases and their content live on the server, so the API can work with them whether or not any client is running. This page is only about the client itself: the displays and devices of a MultiTaction Canvus installation. When you allow access, an integration that holds a Canvus Server API token can:

  • list the client and see its installation name, version and access level (Clients);
  • read the client's workspaces, including which canvas each one shows and which part of the canvas is in view (Workspaces);
  • with read-write access, open a canvas in a workspace, move the view to a region of the canvas, pin the workspace and show or hide its info panel;
  • list the client's display outputs and capture devices (Video outputs, Video inputs), for example to put a capture device on a canvas as a video input widget.

A typical use is a room control panel or a signage script that opens the right canvas on a wall and moves the view to a named area.

The API token belongs to a Canvus Server user. The client only decides whether that server may see and change it.

Configuration

The API access to your Canvus client must be explicitly given to each server the client connects to. This can be done by modifying the client configuration file, mt-canvus.ini.

Place the setting in the [server:<name>] section of the server it applies to, next to the server= address. See Configuration file for the other settings in that section. The following setting is available:

; Controls Rest API access to this client from the server.
; Valid values are:
;   * none - Do not expose this client to Rest API at all.
;   * ro - Allow read-only access to the client state
;   * rw - Allow read-write access to the client state
; DEFAULT: none
; rest-api-access=none

What each value means:

  • none (the default): the client is not listed by the API at all. An empty or unrecognised value also means none.
  • ro: the client is listed with "access": "ro", and you can read its workspaces. A request that changes a workspace, such as opening a canvas or moving the view, returns 403 Forbidden with the message Client is read-only.
  • rw: the client is listed with "access": "rw", and you can read and change its workspaces.

Example: allow a room control system to drive this wall

[server:Canvus Server]
server=canvus.example.com
rest-api-access=rw

Example: let a monitoring dashboard see the wall but not change it

[server:Canvus Server]
server=canvus.example.com
rest-api-access=ro

Note

The client must be restarted for the change to have an effect.

Tip

Each [server:<name>] section has its own rest-api-access setting. A client that connects to two servers can allow read-write access from one and no access from the other.

Info