Canvus REST API

The Canvus REST API gives you programmatic control over a Canvus Server -- the collaborative canvas platform by MultiTaction. Use it to create and manage canvases, place content (notes, images, videos, PDFs, web browsers), control connected display clients, and automate administrative tasks like user management and licensing.

With the API you can build integrations that push live data dashboards to wall displays, automate meeting room canvas provisioning, synchronize content from external systems, or build custom control panels for multi-display environments.

Quick Start

Everything below assumes your Canvus Server is reachable at https://canvus.example.com. Replace that with your actual server address.

Step 1 -- Check server connectivity (no authentication required):

curl https://canvus.example.com/api/v1/server-info

You should get back a JSON object containing the server version.

Step 2 -- Authenticate and get a token:

curl -X POST https://canvus.example.com/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-password"}'

The response includes a token. Copy it for the next step.

Step 3 -- List all canvases:

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

You now have a JSON array of every canvas visible to your account. Each canvas object includes its id, which you use to interact with its contents.

Step 4 -- Create a note on a canvas:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the API", "background_color": "#FFEB3B"}' \
  https://canvus.example.com/api/v1/canvases/CANVAS_ID/notes

Replace CANVAS_ID with an id value from step 3. A yellow note appears on the canvas.

Base URL and Versioning

All API endpoints are prefixed with /api/v1/.

https://canvus.example.com/api/v1/{resource}

The API uses a single major version number. The current major version is v1. Backward-incompatible changes would require a new major version, but new fields and endpoints can be added within v1 without breaking existing clients.

The exact minor version (currently v1.3, introduced in Canvus 3.5) is available from the server-info endpoint.

Authentication

Most endpoints require authentication. The exceptions are explicitly noted in their documentation -- primarily server-info, server-config (read-only), and canvases with shared link access enabled.

Private-Token Header

This is the standard authentication method. Pass your token in the Private-Token HTTP header on every request:

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

Call the login endpoint with an email and password. The returned token expires after 24 hours.

curl -X POST https://canvus.example.com/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@example.com", "password": "s3cureP@ss"}'

The remember field is optional (boolean, defaults to false). When set to true, the token lifetime is extended from the default 24 hours to 14 days. This works on password, token, and SAML login paths.

curl -X POST https://canvus.example.com/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@example.com", "password": "s3cureP@ss", "remember": true}'

To invalidate a temporary token before it expires:

curl -X POST -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/users/logout

Permanent API Access Tokens

For long-running integrations, create a permanent access token that does not expire. You can create one through the Canvus web dashboard under your user profile, or via the API:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline Token"}' \
  https://canvus.example.com/api/v1/users/USER_ID/access-tokens

See Access Tokens for the full endpoint reference.

SAML SSO

Canvus supports SAML-based single sign-on. When SAML is enabled on the server, authentication flows through /api/v1/users/login/saml with a SAML assertion. See Users for details.

Shared Canvas Links

Canvases can be configured with link-based sharing that allows unauthenticated access. When a canvas has link sharing set to "View" or "Edit", certain canvas endpoints (canvas details, widgets, notes, images, etc.) can be accessed without a Private-Token header. See Canvases for details on shared link permissions.

Request and Response Format

The API uses JSON for all request and response bodies unless otherwise noted.

Content-Type for JSON requests: application/json
Content-Type for file uploads: multipart/form-data

When uploading files (images, videos, PDFs, background images), send a multipart/form-data request with:

data -- the file part (required)
json -- a JSON metadata part (optional, for setting widget properties at creation time)

Example file upload:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -F "data=@presentation-slide.png" \
  -F 'json={"title": "Q4 Results", "location": {"x": 500, "y": 300}}' \
  https://canvus.example.com/api/v1/canvases/CANVAS_ID/images

All successful responses return JSON with HTTP status 200. The response body is either a single JSON object (for single-resource operations) or a JSON array (for list operations).

Status Codes

The API returns the following HTTP status codes:

200 OK -- Request succeeded. Returned for all successful GET, POST, PATCH, and DELETE operations. The response body contains the resource as JSON (or an empty body for DELETE).
400 Bad Request -- The request is malformed or a required field is missing. Check the error message for specifics.
401 Unauthorized -- Authentication is missing or the token is invalid/expired.
402 Payment Required -- The server license is invalid, expired, or does not cover this operation.
403 Forbidden -- The authenticated user does not have permission for this operation. For example, a non-admin user trying to manage other users.
404 Not Found -- The requested resource does not exist. Verify the ID in the URL.
405 Method Not Allowed -- The HTTP method is not supported on this endpoint. For example, sending PUT to an endpoint that only accepts PATCH.
409 Conflict -- The operation conflicts with the current state of a resource. For example, creating a user with an email that already exists.
500 Internal Server Error -- An unexpected error occurred on the server. If this persists, check the server logs.
501 Not Implemented -- The endpoint exists but the functionality is not yet available.

Error Handling

When a request fails, the response body contains a JSON object with a msg field describing the problem:

{
  "msg": "Permission denied"
}

Error messages are human-readable and specific to the failure:

{
  "msg": "Canvas width must be at least 1200 and height must be at least 800"
}

{
  "msg": "401 Unauthorized"
}

Always check the HTTP status code first, then read the msg field for actionable detail.

Real-time Streaming

Most GET endpoints support real-time streaming via the ?subscribe query parameter. When you add ?subscribe to a request, the server holds the connection open and pushes updates as they occur.

Starting a Stream

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/canvases/CANVAS_ID/notes?subscribe"

How the Stream Works

The server immediately sends the current state of the resource(s) as the first message.
Whenever the resource changes, the server sends an updated JSON message.
Messages are separated by newline (\n) characters.
The server periodically sends extra newline characters as keepalive pings (default: every 15 seconds). Your parser must tolerate empty lines between messages.
The connection stays open indefinitely until the server shuts down, the network drops, or the token is revoked.

The `state` Field

Every resource in a streamed response includes a read-only state field:

"state": "normal" -- the resource exists and is live
"state": "deleted" -- the resource has been destroyed

This lets you detect deletions in real time without polling.

Parsing the Stream

Each message is a complete JSON object (or array of objects for list endpoints), followed by one or more newlines. A minimal parser should:

Buffer incoming data
Split on newlines
Discard empty lines (keepalives)
Parse each non-empty line as JSON

Reconnection Strategy

If the connection drops:

Wait 1-2 seconds before reconnecting
Reconnect with the same ?subscribe request
The server will send the full current state as the first message, so you do not need to track deltas

The access token used for a subscription will not expire while the stream is active. Revoking the token (via logout) terminates the stream.

Pagination

Currently, only the Audit Log endpoint returns paginated results. Other endpoints return the full result set. The response includes a Link HTTP header with URLs for navigating between pages:

Link: <https://canvus.example.com/api/v1/audit-log?page=2>; rel="next",
      <https://canvus.example.com/api/v1/audit-log?page=5>; rel="last"

Parse the Link header to discover the next and previous pages. Other endpoints return full result sets without pagination.

Common Patterns

CRUD Operations

Most resources follow the same pattern:

List: GET /api/v1/{resource} -- returns a JSON array
Get one: GET /api/v1/{resource}/:id -- returns a single JSON object
Create: POST /api/v1/{resource} -- send JSON body, returns the created object
Update: PATCH /api/v1/{resource}/:id -- send only the fields you want to change
Delete: DELETE /api/v1/{resource}/:id -- returns 200 on success

Server-Scoped vs Canvas-Scoped Resources

Some resources live at the server level:

/api/v1/canvases
/api/v1/users
/api/v1/groups

Content resources live inside a canvas and require a canvas ID in the path:

/api/v1/canvases/:canvas_id/notes
/api/v1/canvases/:canvas_id/images
/api/v1/canvases/:canvas_id/videos

Client resources are scoped to a connected Canvus client application:

/api/v1/clients/:client_id/workspaces
/api/v1/clients/:client_id/video-outputs

Every widget on a canvas has a depth field (a floating-point number) that controls its z-order. Higher values render on top of lower values. When creating or updating widgets, set depth to control stacking order.

File Upload Pattern

For content types that involve files (images, videos, PDFs), creation uses multipart/form-data with two named parts:

data -- the binary file content (required)
json -- a JSON string with metadata like title, location, size (optional)

Downloads use a dedicated /download sub-path that returns the raw file with a Content-Disposition: attachment header:

curl -H "Private-Token: YOUR_TOKEN" -OJ \
  https://canvus.example.com/api/v1/canvases/CANVAS_ID/images/IMAGE_ID/download

The `state` Field

All resources include a state field. In normal API responses this is always "normal". It becomes meaningful in streaming contexts where "deleted" signals that the resource has been removed. See Real-time Streaming above.

Pinning Widgets

Widgets can be pinned to prevent interactive users from moving or resizing them. Set "pinned": true on any widget via PATCH. Pinned widgets remain fully controllable through the API.

API Reference

Server Management

Server Info -- Server version and runtime information. No authentication required.
Server Config -- Read and update server configuration settings (SMTP, SSL, registration, etc.).
License -- View license status, install or activate licenses.

Identity and Access

Users -- Create, update, block, and delete user accounts. Login, logout, password reset, and SAML SSO.
Groups -- Manage user groups and group membership.
Access Tokens -- Create and manage permanent API access tokens for users.
Audit Log -- Query and export the server audit trail (admin only).

Canvases and Organization

Canvases -- Create, list, rename, copy, move, and delete canvases. Manage permissions, backgrounds, color presets, and shared links.
Canvas Folders -- Organize canvases into folders with permissions.

Content Widgets

Notes -- Sticky notes with text, background color, and title.
Images -- Upload and manage image widgets. Download original files.
Videos -- Upload and manage video widgets. Control playback state.
PDFs -- Upload and manage PDF widgets with page navigation.
Browsers -- Embedded web browser widgets with URL control.

Advanced Widgets

Anchors -- Named anchor points for navigation and connector endpoints.
Connectors -- Lines connecting widgets with configurable endpoints, tips, and colors.
Tables -- Grid-based table widgets with configurable rows, columns, and cell content.
IP Videos -- Network video stream widgets (RTSP, HTTP, etc.).
RDP Connections -- Remote desktop connection widgets.

System Resources

Clients -- Connected Canvus client applications.
Workspaces -- Workspaces within connected clients, including view control and canvas assignment.
Widgets -- Read all widgets on a canvas regardless of type.
Uploads Folder -- Upload files to a canvas without creating a specific widget type.
Video Inputs -- Video capture devices available on connected clients.
Video Outputs -- Display outputs on connected clients.
Mipmaps -- Tiled image pyramid access for high-resolution asset rendering.

History

Changelog -- Version history of API changes.

Canvus REST API

Quick Start

Base URL and Versioning

Authentication

Private-Token Header

Temporary Tokens via Login

Permanent API Access Tokens

SAML SSO

Shared Canvas Links

Request and Response Format

Status Codes

Error Handling

Real-time Streaming

Starting a Stream

How the Stream Works

The state Field

Parsing the Stream

Reconnection Strategy

Pagination

Common Patterns

CRUD Operations

Server-Scoped vs Canvas-Scoped Resources

Widget Depth Ordering

File Upload Pattern

The state Field

Pinning Widgets

API Reference

Server Management

Identity and Access

Canvases and Organization

Content Widgets

Advanced Widgets

System Resources

History

The `state` Field

The `state` Field