Skip to content

Automation and bots

The MultiTaction Canvus REST API covers canvases, folders, permissions, users, groups and every type of canvas content. That makes routine administration and content upkeep scriptable. This page shows common jobs and the calls behind them.

Run each job under its own service account. Jobs that manage users, groups or the audit log need an administrator account; content jobs need only edit on the canvases they touch.

Provision meeting canvases from a template

Keep a template canvas in a folder of its own, then copy it for each meeting and give the attendees access.

# 1. Copy the template into the meetings folder. "cancel" returns 409
#    instead of silently skipping when a canvas with that name exists.
NEW=$(curl -s -X POST -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"folder_id\": \"$MEETINGS_FOLDER\", \"conflicts\": \"cancel\"}" \
  https://canvus.example.com/api/v1/canvases/$TEMPLATE/copy | jq -r .id)

# 2. Rename it
curl -s -X PATCH -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Project review 2026-11-12"}' \
  https://canvus.example.com/api/v1/canvases/$NEW

# 3. Give the project group edit access
curl -s -X POST -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"groups": [{"id": 12, "permission": "edit"}]}' \
  https://canvus.example.com/api/v1/canvases/$NEW/permissions

# 4. Seed an agenda note
curl -s -X POST -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Agenda", "text": "1. Status\n2. Risks\n3. Next steps", "background_color": "#FFEB3B"}' \
  https://canvus.example.com/api/v1/canvases/$NEW/notes

Copy into a different folder from the template's own. Renaming the copy straight away frees the template's name in the meetings folder for the next run.

To stamp a single widget from a template canvas into an existing canvas, use POST /canvases/{id}/widgets/clone with source_canvas_id and source_widget_id. See Widgets.

Sync users and groups from your directory

A nightly job can mirror joiners, movers and leavers from your identity system into Canvus accounts and groups.

Event Call
Joiner POST /users with name and email, then POST /groups/{id}/members with {"id": USER_ID}
Mover DELETE /groups/{old}/members/{user_id}, then POST /groups/{new}/members
Leaver POST /users/{id}/block to suspend, or DELETE /users/{id} to remove
Returner POST /users/{id}/unblock

Match accounts on email, which is unique on the server. Read the current state first with GET /users and GET /groups/{id}/members, then send only the differences.

When you create a user without a password, check the response for generated_password and email_send_error. Which one appears depends on whether the server can send email. See Authentication and service accounts and Users.

Keep a status board up to date

A board of notes on a canvas can show live values from another system: build status, ticket counts, room bookings. Create the notes once, store their id values, then update the text on a schedule.

import requests

API = "https://canvus.example.com/api/v1"
canvus = requests.Session()
canvus.headers["Private-Token"] = "SERVICE_ACCOUNT_TOKEN"


def set_status(canvas_id, note_id, text, ok):
    canvus.patch(f"{API}/canvases/{canvas_id}/notes/{note_id}", json={
        "text": text,
        "background_color": "#A5D6A7" if ok else "#EF9A9A",
    }).raise_for_status()

Send a PATCH only when a value changes. Every update is pushed to every Canvus client showing the canvas, so needless writes cost network traffic on the wall.

To keep people from moving the board around, set "pinned": true on its widgets. Pinned widgets stay where they are for touch users and remain fully editable through the API.

Forward canvas activity to another system

Open a stream on a canvas and pass selected changes on, for example new notes in an "Escalations" anchor zone to your ticketing system or chat.

GET /api/v1/canvases/{id}/notes?subscribe

The first message lists every note. Each later message is an array with the note that changed. Merge by id, compare with what you have seen, and forward the new items. Streaming and change tracking has a reader you can start from.

Export the audit log for compliance

An administrator account can pull the audit trail on a schedule and hand it to your log archive or SIEM.

curl -s -H "Private-Token: $ADMIN_TOKEN" -o audit-2026-11.csv \
  "https://canvus.example.com/api/v1/audit-log/export-csv?created_after=2026-11-01T00:00:00.000Z&created_before=2026-11-30T23:59:59.999Z"

The JSON form, GET /audit-log, is paginated with a cursor and filters by created_after, created_before, target_type, target_id and author_id. See Audit log.

Reset a demo canvas every night

For showrooms and training rooms, switch a canvas to demo mode, arrange it, and save that state. A scheduled job then restores it.

# Once: switch to demo mode and save the arranged state
curl -X PATCH -H "Private-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode": "demo"}' https://canvus.example.com/api/v1/canvases/$CANVAS
curl -X POST -H "Private-Token: $TOKEN" https://canvus.example.com/api/v1/canvases/$CANVAS/save

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

See Canvases.

Design for retries

The API has no batch or transaction endpoint, and Canvus Server does not rate-limit calls. Build your jobs so they can stop and start safely:

  • Read state first and write only the differences, so a rerun changes nothing that is already right.
  • Record the id of everything you create, so a retry updates it instead of creating a duplicate.
  • Pace your writes, and back off on 500 responses.
  • Prefer one ?subscribe stream to frequent polling.

See Limits and operations.