Skip to content

Digital signage and content push

A MultiTaction Canvus wall can double as a display surface that other systems feed. With the REST API you can place images, videos, PDFs and live web pages on a canvas, change them on a schedule, and control which canvas each wall shows and where it looks.

Before you start

  • A service account with edit on the canvases you push to. See Authentication and service accounts.
  • API access on each wall client. To open canvases or move the view on a wall, the Canvus client on that wall must allow it. In the client's mt-canvus.ini, in the [server:...] section for your Canvus Server, set rest-api-access=rw, then restart the client. The default, none, hides the client from the API. ro lets you read its state but not change it; a change request then returns 403 "Client is read-only". See Canvus API in the client documentation.

Push content to a canvas

Upload files with multipart/form-data: a data part for the file and a json part for where and how to show it.

curl -X POST -H "Private-Token: $TOKEN" \
  -F 'data=@q4-results.png' \
  -F 'json={"title": "Q4 results", "location": {"x": 400, "y": 300}, "pinned": true}' \
  https://canvus.example.com/api/v1/canvases/$CANVAS/images
Content Create with Change with
Image POST /canvases/{id}/images PATCH .../images/{id} (title, location, size, pinned)
Video POST /canvases/{id}/videos PATCH .../videos/{id} (playback_state, playback_position, muted)
PDF POST /canvases/{id}/pdfs PATCH .../pdfs/{id} (index for the page shown)
Web page or dashboard POST /canvases/{id}/browsers with url PATCH .../browsers/{id} with a new url
Network video stream POST /canvases/{id}/ip-videos with source PATCH .../ip-videos/{id}
Text POST /canvases/{id}/notes PATCH .../notes/{id} (text, background_color)

playback_state takes "PLAYING", "PAUSED" or "STOPPED", in capitals. On Canvus Server 26.10.0 or later, videos also accept looping: true.

Show a live dashboard

A browser widget shows any web page your wall can reach, so an existing dashboard becomes signage without new code:

curl -X POST -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://dashboards.example.com/sales", "size": {"width": 1920, "height": 1080}, "pinned": true}' \
  https://canvus.example.com/api/v1/canvases/$CANVAS/browsers

To rotate between pages, PATCH the same widget with a new url on a timer.

Keep visitors from rearranging content

Set "pinned": true on widgets you place. Touch users cannot move or resize a pinned widget, and the API can still change it. On Canvus Server 26.10.0 or later, "input_locked": true also stops touch users operating the widget.

Control what each wall shows

List the Canvus clients connected to the server, then their workspaces:

curl -H "Private-Token: $TOKEN" https://canvus.example.com/api/v1/clients
curl -H "Private-Token: $TOKEN" https://canvus.example.com/api/v1/clients/$CLIENT/workspaces

Open a canvas in a workspace:

curl -X POST -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"canvas_id\": \"$CANVAS\"}" \
  https://canvus.example.com/api/v1/clients/$CLIENT/workspaces/0/open-canvas

Controlling a wall needs no administrator rights: any user's token works, provided the client allows API access (rest-api-access=rw). Once someone has opened a canvas on a workspace under their own user account, only that user's token can control the workspace, and administrator tokens are refused too. Leave a signage wall signed out, or sign it in with your service account.

The wall opens the canvas under its own sign-in, not under your token's user. Without user_email, it uses the account already signed in on that workspace, or Guest when nobody is signed in, so a canvas for a signed-out wall must be shared by link. With user_email, the wall uses that account if it is already signed in there; otherwise it shows a sign-in page for that account and waits for someone to sign in at the wall. See Workspaces.

Then adjust the workspace with PATCH /clients/{id}/workspaces/{index}:

  • view_rectangle moves and zooms the view, so you can frame one area of a large canvas;
  • pinned: true stops touch users panning or zooming the workspace;
  • info_panel_visible: false hides the info panel for a cleaner display.

In Canvus 26.11, a view_rectangle change can return 200 without the wall's view moving, so check the wall before you build on it. See Workspaces for how view_rectangle is applied, and Video outputs for controlling individual display outputs.

Run a playlist

Two simple ways to cycle content:

  • Switch canvases. Prepare one canvas per scene and call open-canvas on a schedule. Each scene keeps its own layout.
  • Change content in place. Keep one canvas and PATCH its widgets: a new url on a browser, a new page index on a PDF, new text on a note.

Anchors help with layout. Create named zones with POST /canvases/{id}/anchors and arrange each scene inside its own zone, then move the workspace view between zones with view_rectangle.

Return to a known state

For a wall that visitors touch, put the canvas in demo mode, arrange it and save it. Restore it on a schedule, for example every night or every hour:

curl -X POST -H "Private-Token: $TOKEN" \
  https://canvus.example.com/api/v1/canvases/$CANVAS/restore

See Canvases.

Watch the walls

GET /clients?subscribe streams changes to the list of connected clients, so a monitoring job can tell when a wall drops off the server. Each change arrives as an array with the clients that changed; a client that disconnects arrives with "state": "deleted". See Streaming and change tracking.

Limits to plan for

  • Writes need edit on the canvas and a valid server license.
  • Uploads must finish within the server's 300 s request deadline. Test large videos over the link you will use.
  • The API does not rate-limit calls. Pace scheduled updates so each one changes something.

See Limits and operations.