Skip to content

Canvus API

The Canvus API is a RESTful API that enables automation and manipulation of content in Canvus from your own application.

Compatibility

The API is versioned using a single number. The number symbolizes the major version as described by semantic versioning. This means that backwards incompatible changes will require this version number to change. Since the minor version is not explicit, it allows for a stable API endpoint, but new features can be added to the API in the same version number. The minor version of the API can be found through the server info endpoint.

Current Status

The current version of the API is v1.2. It was added in Canvus 3.1.

Basic Usage

API requests should be prefixed with api and the API major version. For example, the root of the v1.1 API is at /api/v1.

Example of a valid API request using cURL:

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

The API uses JSON to serialize data.

Authentication

Normally all API requests require authentication, except requests to specific endpoints like /server-info or /server-config. These exceptions are explicitly mentioned in the documentation.

In addition, Canvus 3.1 introduced shared links that may allow unauthenticated access to a canvas. You can read more about it here.

An error message will be returned with status code 401 if authentication information is missing or invalid:

{
  "message": "401 Unauthorized"
}

Access Tokens

API requests should be authenticated by passing an access token as Private-Token header.

There are two ways to obtain an access token:

  • Call the /login endpoint with username and password, assuming password authentication is enabled on the server. This method will issue a temporary token that expires after 24 hours.
  • Create an access token using either the /access-tokens endpoint or the Canvus web UI. Access tokens created using this method will not expire.

Example of using access token in a request:

curl --header "Private-Token: <access_token>" https://canvus.example.com/api/v1/canvases

Status Codes

API requests return different status codes based on the context of the request. If a request fails, the caller can get insight into what went wrong. The table below shows status codes for request types when no error occurs.

Request type Description

GET Return 200 and the resource(s) as JSON. POST Return 200 and the result as JSON. PATCH Return 200 and the resource as JSON. DELETE Return 200.

: Overview of API request status codes

Error Reporting

The API will answer with a status code other than 200 in case of an error. Typically this is one of the 4xx HTTP status codes because the request validation fails. For example:

  • Access token is invalid or missing
  • A required attribute of the request is missing, for example the data for an image is not given
  • An attribute did not pass validation, for example specified canvas does not exist
  • The user associated with the access token doesn\'t have permission to access the resource or execute an action

The JSON result will include a human-readable message about what went wrong, for example:

{
  "msg": "Permission denied"
}

or

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

Streaming

You can use streaming to listen to changes in resources in real-time.

Most GET API requests can be used for streaming. To enable it, pass subscribe parameter with the request.

When responding to a streaming request, the Canvus server will hold the connection open indefinitely (barring a server-side error, excessive client lag, network hiccups or server maintenance). The response will be a JSON stream. The stream starts with the state of the requested resource(s) at the moment of the API call.

The access token used to subscribe to a stream will not expire until the stream is active. Revoking the token terminates the stream.

JSON Stream

The JSON stream returns messages as JSON objects (or arrays of objects, depending on the endpoint) separated by newline (\n) characters.

While parsing the stream, clients must tolerate extra newline characters placed between messages. These characters are sent as periodic \"keep-alive\" messages to the clients that the connection is still alive during times when there are no changes to the resource.

All returned resources include a read-only state parameter that is either normal for live objects and changes to deleted for objects that are destroyed.

API Resources

Resources available in the standalone context:

Resource Endpoints

Access Tokens /access-tokens Canvases /canvases Canvas Folders /canvas-folders Canvus Clients /clients Groups /groups License /license Server Config /server-config Server Info /server-info Users /users Audit Log /audit-log

Resources available in the canvases context:

Resource Endpoints

Anchors /canvases/:id/anchors Notes /canvases/:id/notes Images /canvases/:id/images Browsers /canvases/:id/browsers Videos /canvases/:id/videos PDFs /canvases/:id/pdfs Widgets /canvases/:id/widgets Uploads Folder /canvases/:id/uploads-folder

API resources available in the clients context:

Resource Endpoints

Workspaces /clients/:id/workspaces

Info

Changelog

Changelog for the Canvus API can be found here.