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.2) 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 '{"description": "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

Field names in requests and responses use underscores, for example widget_type and parent_id. The exceptions use hyphens: host-id on IP video, video input and RDP widgets, and connection-name and content-id on RDP widgets.

Successful responses return HTTP status 200. Most return JSON: a single object for single-resource operations, or an array for list operations. File downloads return the raw file instead, and can also return 206 Partial Content or 304 Not Modified for range or conditional requests. Some actions (for example adding a group member) return an empty body.

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 and some actions).
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 by the API. Only GET, POST, PATCH, and DELETE are accepted; any other method, such as PUT, returns 405. A supported method sent to an endpoint that does not accept it returns 400 Bad Request.
409 Conflict -- The operation conflicts with the current state of a resource. For example, creating a canvas with a name that already exists in the target folder.
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.

Current behavior

The status codes above are the intended behavior. The server currently differs in a few cases, which are being corrected:

A Private-Token that is present but invalid or expired returns 403 Forbidden with {"msg": "Invalid token"}, not 401 Unauthorized. A missing token returns 401 as documented.
Some permission failures in user and group management return 401 Unauthorized instead of 403 Forbidden.
Some requests for a resource that does not exist return 400 Bad Request or 500 Internal Server Error instead of 404 Not Found.
501 Not Implemented is currently sent as 500 Internal Server Error.

The individual pages note where their endpoints are affected.

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": "The request should be authenticated. Private-Token header is missing."
}

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 until the server shuts down, the network drops, the token is revoked, or the user account is deleted. A stream for a single resource also ends after that resource is deleted: the server sends a final message with "state": "deleted" and closes the connection.

The `state` field

Most resources in a streamed response include 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. Groups and access tokens include state only in deletion events.

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. Pagination is cursor-based. When more results exist, the response includes a Link HTTP header with the URL of the next page:

Link: <https://canvus.example.com/api/v1/audit-log?per_page=50&cursor=1234>; rel="next"

Follow the rel="next" URL to fetch the next page. There are no previous-page or last-page links, and the header is omitted on the last page.

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 (adding a group member returns an empty body)
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, except connectors and the canvas background, 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

Most resources include a state field (widgets, canvases, folders, users, clients, and workspaces, among others). 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 except connectors 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, 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.
Annotations -- Freehand pen strokes drawn on a widget or directly on the canvas.
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 and notes into a canvas's uploads folder. Each upload creates a widget of the matching 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

Permanent API access tokens

SAML SSO

Shared canvas links

Request and response format

Status codes

Current behavior

Error handling

Real-time streaming

Starting a stream

How the stream works

The `state` field

Parsing the stream

Reconnection strategy

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

See also

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

Current behavior

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

See also

The `state` field

The `state` field