

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 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.

Overview of API request status codes 
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` .

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"
}

           

            {
  "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`
Connectors	`/canvases/:id/connectors`

API resources available in the clients context:

Resource	Endpoints
Workspaces	`/clients/:id/workspaces`

List Tokens 

Gets the access tokens of a user. Regular users can see only their own tokens, administrators can list access tokens of other users. The actual tokens are not returned.

             GET /users/:id/access-tokens

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1001/access-tokens

            

Example response:

             [
  {
    "created_at": "2021-07-02T06:38:36.025",
    "description": "First token",
    "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp"
  }
]

            

Single Token 

Gets info about a single access token.

             GET /users/:id/access-tokens/:token-id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user
`token-id` (path)	string	yes	The ID of the token
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1001/access-tokens/JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp

            

Example response:

             {
  "created_at": "2021-07-02T06:38:36.025",
  "description": "First token",
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp"
}

            

Create Token 

Creates a new access token. The return value includes the plain text token. It is not possible to retrieve the plain text token afterwards.

             POST /users/:id/access-tokens

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user
`description`	string	yes	Description of the new token

             curl -X POST -H "Private-Token: W1bns7ZYuN_u7fQTR3i6L0JopiRCGsbNjXRw7Z-yX0E" -d '{"description":"Second token"}' https://canvus.example.com/api/v1/users/1001/access-tokens

            

Example response:

             {
  "created_at": "2021-07-02T09:38:36.193",
  "description": "Second token",
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi44SUR3aHJaY2E1UUVaOGZUeTRDejB2ZnQzWGovclQ2",
  "plain_token": "QbhGvPSeh0hLSgfJb120I6by4ao1J5RRd59XmNOQq2g"
}

            

Change Token Description 

Changes an access token description.

             PATCH /users/:id/access-tokens/:token-id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user
`token-id` (path)	string	yes	The ID of the token
`description`	string	yes	New description

             curl -X PATCH -H "Private-Token: W1bns7ZYuN_u7fQTR3i6L0JopiRCGsbNjXRw7Z-yX0E" -d '{"description":"Updated description"}' https://canvus.example.com/api/v1/users/1001/access-tokens/JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp

            

Example response:

             {
  "created_at": "2021-07-02T06:38:36.025",
  "description": "Updated description",
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp"
}

            

Delete Token 

Deletes an access token. The token is revoked and can not be used anymore.

             DELETE /users/:id/access-tokens/:token-id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user
`token-id` (path)	string	yes	The ID of the token

             curl -X DELETE -H "Private-Token: W1bns7ZYuN_u7fQTR3i6L0JopiRCGsbNjXRw7Z-yX0E" https://canvus.example.com/api/v1/users/1001/access-tokens/JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp

            

Content from: anchors page

Anchors API 

The anchors API operates on anchors on a canvas.

List Anchors 

Gets all anchors of the specified canvas.

             GET /canvases/:id/anchors

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors

            

Example response:

             [
  {
    "anchor_index": 0,
    "anchor_name": "New anchor",
    "depth": 0,
    "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
    "location": {
      "x": 4676.818359375,
      "y": 2432.80126953125
    },
    "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 800,
      "width": 1200
    },
    "state": "normal",
    "widget_type": "Anchor"
  }
]

            

Single Anchor 

Gets a single anchor.

             GET /canvases/:id/anchors/:anchor_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`anchor_id` (path)	uuid	yes	ID of the anchor to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors/5da69125-a5f5-417d-8d8d-a633a0499560

            

Example response:

             {
  "anchor_index": 0,
  "anchor_name": "New anchor",
  "depth": 0,
  "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
  "location": {
    "x": 4676.818359375,
    "y": 2432.80126953125
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "widget_type": "Anchor"
}

            

Create Anchor 

Creates an anchor.

             POST /canvases/:id/anchors

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`depth`	number	no	Depth of the anchor compared to its siblings
`location`	object	no	Location of the anchor relative to its parent
`pinned`	boolean	no	Is the anchor pinned or not
`scale`	number	no	Scale of the anchor
`size`	object	no	Size of the anchor
`anchor_index`	number	no	Index number of the anchor
`anchor_name`	string	no	Name of the anchor

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors

            

Example response:

             {
  "anchor_index": 1,
  "anchor_name": "New anchor",
  "depth": 0,
  "id": "8cf37672-e642-449d-881e-6ee6e42afc16",
  "location": {
    "x": 4632.12841796875,
    "y": 3039.445556640625
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "widget_type": "Anchor"
}

            

Update Anchor 

Updates an anchor.

             PATCH /canvases/:id/anchors/:anchor_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`anchor_id` (path)	uuid	yes	ID of the anchor to update
`depth`	number	no	Depth of the anchor compared to its siblings
`location`	object	no	Location of the anchor relative to its parent
`pinned`	boolean	no	Is the anchor pinned or not
`scale`	number	no	Scale of the anchor
`size`	object	no	Size of the anchor
`anchor_index`	number	no	Index number of the anchor
`anchor_name`	string	no	Name of the anchor

             curl -X PATCH -H "Private-Token: <access token>" -d '{"anchor_name":"Region 1"}' https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors/5da69125-a5f5-417d-8d8d-a633a0499560

            

Example response:

             {
  "anchor_index": 0,
  "anchor_name": "Region 1",
  "depth": 0,
  "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
  "location": {
    "x": 4676.818359375,
    "y": 2432.80126953125
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "widget_type": "Anchor"
}

            

Delete Anchor 

Deletes an anchor.

             DELETE /canvases/:id/anchors/:anchor_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`anchor_id` (path)	uuid	yes	ID of the anchor to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors/5da69125-a5f5-417d-8d8d-a633a0499560

            

Content from: audit-log page

Audit Log 

The audit log API provides access to the server audit events. You must authenticate as an administrator to use this endpoint.

Get Audit Log 

Gets the list of audit events that match filters. Output of this endpoint is paginated. The link to the next page of results is given in the response Link header. Events are sorted from newest to oldest.

GET /audit-log

Attribute	Type	Required	Description
`created_after` (query)	string	no	Include only events created after given timestamp
`created_before` (query)	string	no	Include only events created befor given timestamp
`target_type` (query)	string	no	Include only events for the given target type
`target_id` (query)	string	no	Include only events for the given target ID
`target_id` (query)	string	no	Include only events for the given autor ID
`per_page` (query)	integer	no	Number of results per page
`cursor` (query)	integer	no	Current page offset. You should get this from Link header

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/audit-log

            

Export Audit Log as CSV 

Exports the audit log as CSV file. Accepts the same set of filters as audit-log endpoint.

GET /audit-log

Attribute	Type	Required	Description
`created_after` (query)	string	no	Include only events created after given timestamp
`created_before` (query)	string	no	Include only events created befor given timestamp
`target_type` (query)	string	no	Include only events for the given target type
`target_id` (query)	string	no	Include only events for the given target ID
`target_id` (query)	string	no	Include only events for the given autor ID

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/audit-log/export-csv

            

Content from: browsers page

Browsers API 

The browsers API operates on web browsers on a canvas.

List Browsers 

Gets all web browsers of the specified canvas.

             GET /canvases/:id/browsers

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers

            

Example response:

             [
  {
    "depth": 0,
    "id": "82796808-84e4-4309-8d76-bd0cee281a22",
    "location": {
      "x": 4932.95068359375,
      "y": 2223.86572265625
    },
    "main_frame_scroll_offset": {
      "x": 0,
      "y": 0
    },
    "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 800,
      "width": 1200
    },
    "state": "normal",
    "title": "",
    "transparent_mode": false,
    "url": "https://www.google.com/",
    "widget_type": "Browser"
  }
]

            

Single Browser 

Gets a single browser.

             GET /canvases/:id/browsers/:browser_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`browser_id` (path)	uuid	yes	ID of the browser to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

            

Example response:

             {
  "depth": 0,
  "id": "82796808-84e4-4309-8d76-bd0cee281a22",
  "location": {
    "x": 4932.95068359375,
    "y": 2223.86572265625
  },
  "main_frame_scroll_offset": {
    "x": 0,
    "y": 0
  },
  "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "title": "",
  "transparent_mode": false,
  "url": "https://www.google.com/",
  "widget_type": "Browser"
}

            

Create Browser 

Creates a browser.

             POST /canvases/:id/browsers

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`depth`	number	no	Depth of the browser compared to its siblings
`location`	object	no	Location of the browser relative to its parent
`parent_id`	uuid	no	ID of the browser's parent
`pinned`	boolean	no	Is the browser pinned or not
`scale`	number	no	Scale of the browser
`size`	object	no	Size of the browser
`title`	string	no	Title of the browser
`transparent_mode`	boolean	no	Is the browser in transparent mode
`main_frame_scroll_offset`	object	no	Scroll offset for the main frame in the browser
`url`	string	no	URL of the web browser

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers

            

Example response:

             {
  "depth": 0,
  "id": "cb1f6489-13c0-4f8a-b94e-3b56ddbd2aba",
  "location": {
    "x": 5010.69287109375,
    "y": 2646.39794921875
  },
  "main_frame_scroll_offset": {
    "x": 0,
    "y": 0
  },
  "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "title": "",
  "transparent_mode": false,
  "url": "https://www.google.com/",
  "widget_type": "Browser"
}

            

Update Browser 

Updates a browser.

             PATCH /canvases/:id/browsers/:browser_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`browser_id` (path)	uuid	yes	ID of the browser to update
`depth`	number	no	Depth of the browser compared to its siblings
`location`	object	no	Location of the browser relative to its parent
`parent_id`	uuid	no	ID of the browser's parent
`pinned`	boolean	no	Is the browser pinned or not
`scale`	number	no	Scale of the browser
`size`	object	no	Size of the browser
`title`	string	no	Title of the browser
`transparent_mode`	boolean	no	Is the browser in transparent mode
`main_frame_scroll_offset`	object	no	Scroll offset for the main frame in the browser
`url`	string	no	URL of the web browser

             curl -X PATCH -H "Private-Token: <access token>" -d '{"url":"www.multitaction.com"}' https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

            

Example response:

             {
  "depth": 0,
  "id": "82796808-84e4-4309-8d76-bd0cee281a22",
  "location": {
    "x": 4932.95068359375,
    "y": 2223.86572265625
  },
  "main_frame_scroll_offset": {
    "x": 0,
    "y": 0
  },
  "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "title": "",
  "transparent_mode": false,
  "url": "www.multitaction.com",
  "widget_type": "Browser"
}

            

Delete Browser 

Deletes a browser.

             DELETE /canvases/:id/browsers/:browser_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`browser_id` (path)	uuid	yes	ID of the browser to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

            

Content from:

Canvas Folders API 

The folders API operates on canvas folders on the server.

List Folders 

Gets a list of all folders.

GET /canvas-folders

Attribute	Type	Required	Description
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvas-folders

            

Example response:

             [
  {
    "access": "edit",
    "folder_id": "",
    "id": "4f517d91-7448-4810-87f2-f6b25e8dc3cd",
    "in_trash": false,
    "name": "",
    "state": "normal"
  },
  {
    "access": "edit",
    "folder_id": "4f517d91-7448-4810-87f2-f6b25e8dc3cd",
    "id": "100",
    "in_trash": false,
    "name": "Guest",
    "state": "normal"
  },
  {
    "access": "edit",
    "folder_id": "100",
    "id": "trash.100",
    "in_trash": false,
    "name": "Trash",
    "state": "normal"
  },
  {
    "access": "owner",
    "folder_id": "4f517d91-7448-4810-87f2-f6b25e8dc3cd",
    "id": "1000",
    "in_trash": false,
    "name": "admin",
    "state": "normal"
  },
  {
    "access": "owner",
    "folder_id": "1000",
    "id": "trash.1000",
    "in_trash": false,
    "name": "Trash",
    "state": "normal"
  },
  {
    "access": "owner",
    "folder_id": "1000",
    "id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
    "in_trash": false,
    "name": "Alice",
    "state": "normal"
  },
  {
    "access": "owner",
    "folder_id": "1000",
    "id": "7d7ef61a-9def-4de5-96bf-c0193252378d",
    "in_trash": false,
    "name": "Bob",
    "state": "normal"
  }
]

            

Single Folder 

Gets a single folder.

             GET /canvas-folders/:id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3

            

Example response:

             {
  "access": "owner",
  "folder_id": "1000",
  "id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
  "in_trash": false,
  "name": "Alice",
  "state": "normal"
}

            

Create Folder 

Creates a folder.

POST /canvas-folders

Attribute	Type	Required	Description
`name`	string	no	Name of the folder
`folder_id`	uuid	no	The ID of the parent folder

             curl -X POST -H "Private-Token: <access token>" -d '{"name":"Notes","folder_id":"b574c9f9-2717-4c95-b6dd-c48d146c28f3"}' https://canvus.example.com/api/v1/canvas-folders

            

Example response:

             {
  "access": "owner",
  "folder_id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
  "id": "293bddf1-8e0e-4306-823e-19e5be9b2349",
  "in_trash": false,
  "name": "Notes",
  "state": "normal"
}

            

Rename Folder 

Renames a folder.

             PATCH /canvas-folders/:id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder to rename
`name`	string	no	Name of the canvas

             curl -X PATCH -H "Private-Token: <access token>" -d '{"name":"Carol"}' https://canvus.example.com/api/v1/canvas-folders/7d7ef61a-9def-4de5-96bf-c0193252378d

            

Example response:

             {
  "access": "owner",
  "folder_id": "1000",
  "id": "7d7ef61a-9def-4de5-96bf-c0193252378d",
  "in_trash": false,
  "name": "Carol",
  "state": "normal"
}

            

Move Folder 

Moves a folder inside another folder.

             POST /canvas-folders/:id/move

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder to copy or move
`folder_id`	uuid	yes	The ID of the destination folder
`conflicts`	string	no	Conflict resolution strategy

             curl -X POST -H "Private-Token: <access token>" -d '{"folder_id":"7d7ef61a-9def-4de5-96bf-c0193252378d","conflicts":"replace"}' https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/move

            

Example response:

             {
  "access": "owner",
  "folder_id": "7d7ef61a-9def-4de5-96bf-c0193252378d",
  "id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
  "in_trash": false,
  "name": "Alice",
  "state": "normal"
}

            

Folders with the same name are merged on move.

The conflicts parameter can take one of the following values:

Value	Description
`skip` (default)	Skips conflicting items
`cancel`	Cancels the whole operation if any conflict would happen as a result
`replace`	Replaces the destination item with the source one if a conflict happens

Copy Folder 

Copies a folder inside another folder.

             POST /canvas-folders/:id/copy

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder to copy or move
`folder_id`	uuid	yes	The ID of the destination folder
`conflicts`	string	no	Conflict resolution strategy

             curl -X POST -H "Private-Token: <access token>" -d '{"folder_id":"7d7ef61a-9def-4de5-96bf-c0193252378d","conflicts":"replace"}' https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/copy

            

Example response:

             {
  "access": "owner",
  "folder_id": "7d7ef61a-9def-4de5-96bf-c0193252378d",
  "id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
  "in_trash": false,
  "name": "Alice",
  "state": "normal"
}

            

Folders with the same name are merged on copy. The only exception is duplicate operation triggered by copying a folder to the same parent.

The conflicts parameter can take one of the following values:

Value	Description
`skip` (default)	Skips conflicting items
`cancel`	Cancels the whole operation if any conflict would happen as a result
`replace`	Replaces the destination item with the source one if a conflict happens

Trash Folder 

Trash a folder by moving it to the trash folder. Note that conflicts parameter is ignored when moving to trash. You can not move items to other users' trash folder.

             POST /canvases/:id/move

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder to trash
`folder_id`	uuid	yes	The ID of the trash folder

             curl -X POST -H "Private-Token: <access token>" -d '{"folder_id":"trash.1000"}' https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/move

            

Example response:

             {
  "access": "owner",
  "folder_id": "trash.1000",
  "id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3",
  "in_trash": true,
  "name": "Alice",
  "state": "normal"
}

            

Delete Folder 

Permanently deletes a folder.

             DELETE /canvas-folders/:id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3

            

Delete Folder Contents 

Deletes all children of a folder, but not the folder itself.

             DELETE /canvas-folders/:id/children

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvas-folders/trash.1000/children

            

Get Permissions 

Gets the permission overrides on a folder.

             GET /canvas-folders/:id/permissions

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvas-folders/7d7ef61a-9def-4de5-96bf-c0193252378d/permissions

            

Example response:

             {
  "editors_can_share": true,
  "groups": [

  ],
  "users": [
    {
      "id": 1000,
      "inherited": false,
      "permission": "owner"
    }
  ]
}

            

Tip

The access field of the /canvas-folders endpoint provides a simple way to find effective permissions of a folder.

Set Permissions 

Sets permission overrides on a folder.

             POST /canvas-folders/:id/permissions

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the folder
`editors_can_share`	boolean	no	If true, users with edit access can change permissions
`users`	array	no	The list of users permissions
`groups`	array	no	The list of groups permissions

Permission object has the following attributes.

Attribute	Type	Required	Description
`id`	integer	yes	The ID of the user of group
`permission`	string	yes	Permission string

The permissions parameter can take one of the following values:

Value	Description
`none`	The principal has no access to the resource
`view`	The principal has read-only access to the resource
`edit`	The principal has edit access to the resource
`owner`	The principal owns the resource

             curl -X POST -H "Private-Token: <access token>" -d '{"editors_can_share":false,"users":[{"id":100,"permission":"edit"}]}' https://canvus.example.com/api/v1/canvas-folders/7d7ef61a-9def-4de5-96bf-c0193252378d/permissions

            

Example response:

             {
  "editors_can_share": false,
  "groups": [

  ],
  "users": [
    {
      "id": 100,
      "inherited": false,
      "permission": "edit"
    },
    {
      "id": 1000,
      "inherited": false,
      "permission": "owner"
    }
  ]
}

            

Content from:

Canvases 

The canvases API operates on canvases on the server.

Shared Links 

Canvus 3.1 introduced shared links. If enabled, this feature allows unauthenticated access to a canvas without providing an access token for API requests.

If a canvas has link_permission attribute equal to edit or view , the Private-Token header in the API requests may be omitted.

In this case, the regular permission checks are ignored and access to the canvas is granted as Guest user with edit or view permission correspondingly. If the Guest user is blocked on the server, this unauthenticated access will not be available.

A valid Private-Token may be given as usual when accessing a canvas with a shared link. In this case the user associated with the token is used to access the canvas, but the effective permission granted is at least as allowed by the link_permission attribute.

You can find out or modify the link_permission value using /permissions endpoint.

List Canvases 

Gets a list of all canvases.

GET /canvases

Attribute	Type	Required	Description
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases

            

Example response:

             [
  {
    "access": "owner",
    "asset_size": 0,
    "created_at": "2021-10-28T12:27:39.426Z",
    "folder_id": "1034",
    "id": "020b063d-0086-49a5-8dd0-965b8e117216",
    "in_trash": false,
    "mode": "normal",
    "modified_at": "2021-10-28T12:27:39.426Z",
    "name": "New canvas",
    "preview_hash": "",
    "state": "normal"
  },
  {
    "access": "owner",
    "asset_size": 0,
    "created_at": "2021-10-28T12:27:39.455Z",
    "folder_id": "1034",
    "id": "9c21f153-ac8b-4ad3-83c5-60c282ee9359",
    "in_trash": false,
    "mode": "demo",
    "modified_at": "2021-10-28T12:27:39.455Z",
    "name": "New canvas (1)",
    "preview_hash": "",
    "state": "normal"
  }
]

            

Single Canvas 

Gets a single canvas.

             GET /canvases/:id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216

            

Example response:

             {
  "access": "owner",
  "asset_size": 0,
  "created_at": "2021-10-28T12:27:39.426Z",
  "folder_id": "1034",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2021-10-28T12:27:39.426Z",
  "name": "New canvas",
  "preview_hash": "",
  "state": "normal"
}

            

Get Canvas Preview 

Downloads the preview of the canvas, if available.

             GET /canvases/:id/preview

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/preview

            

Example response:

             {
  "msg": "Canvas 020b063d-0086-49a5-8dd0-965b8e117216 doesn't have preview"
}

            

Create Canvas 

Creates a canvas.

POST /canvases

Attribute	Type	Required	Description
`name`	string	no	Name of the canvas
`folder_id`	uuid	no	The ID of the parent folder . By default the new canvas is created in the user's home folder.

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases

            

Example response:

             {
  "access": "owner",
  "asset_size": 0,
  "created_at": "2021-10-28T12:27:39.656Z",
  "folder_id": "1034",
  "id": "70c54ca9-a31d-45d8-af84-bacc9b708caf",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2021-10-28T12:27:39.656Z",
  "name": "New canvas (2)",
  "preview_hash": "",
  "state": "normal"
}

            

Change Canvas 

Can be used to rename a canvas or change it from regular to demo and vice versa.

Note

You can't change folder_id using this endpoint. Use copy or move endpoints.

             PATCH /canvases/:id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas to update
`name`	string	no	Name of the canvas
`mode`	string	no	Demo-state of the canvas

The mode parameter can take one of the following values:

Value	Description
`normal`	Canvas is not a demo canvas
`demo`	Canvas is a demo canvas

             curl -X PATCH -H "Private-Token: <access token>" -d '{"name":"Hello"}' https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216

            

Example response:

             {
  "access": "owner",
  "asset_size": 0,
  "created_at": "2021-10-28T12:27:39.426Z",
  "folder_id": "1034",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2021-10-28T12:27:39.426Z",
  "name": "Hello",
  "preview_hash": "",
  "state": "normal"
}

            

Restore Demo Canvas 

Restores the state of a demo canvas to the last saved state.

             POST /canvases/:id/restore

            

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/restore

            

Save Demo State 

Updates the saved demo canvas state with the current changes.

             POST /canvases/:id/save

            

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/save

            

Move Canvas 

Moves a canvas to another folder.

             POST /canvases/:id/move

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas to copy or move
`folder_id`	uuid	yes	The ID of the destination folder
`conflicts`	string	no	Conflict resolution strategy

             curl -X POST -H "Private-Token: <access token>" -d '{"folder_id":"47c0e2cb-a299-4f3b-ac9a-810cc7c242d3","conflicts":"replace"}' https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/move

            

Example response:

             {
  "access": "owner",
  "asset_size": 0,
  "created_at": "2021-10-28T12:27:39.426Z",
  "folder_id": "47c0e2cb-a299-4f3b-ac9a-810cc7c242d3",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2021-10-28T12:27:39.426Z",
  "name": "Hello",
  "preview_hash": "",
  "state": "normal"
}

            

The conflicts parameter can take one of the following values:

Value	Description
`skip` (default)	Synonym for `cancel`
`cancel`	Cancels the operation if a conflict would happen as a result
`replace`	Replaces the destination canvas with the source one if a conflict happens

Copy Canvas 

Copies a canvas to another folder.

             POST /canvases/:id/copy

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas to copy or move
`folder_id`	uuid	yes	The ID of the destination folder
`conflicts`	string	no	Conflict resolution strategy

             curl -X POST -H "Private-Token: <access token>" -d '{"folder_id":"47c0e2cb-a299-4f3b-ac9a-810cc7c242d3","conflicts":"replace"}' https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/copy

            

Example response:

             {
  "access": "owner",
  "asset_size": 0,
  "created_at": "2021-10-28T12:27:39.426Z",
  "folder_id": "47c0e2cb-a299-4f3b-ac9a-810cc7c242d3",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": false,
  "mode": "normal",
  "modified_at": "2021-10-28T12:27:39.426Z",
  "name": "Hello",
  "preview_hash": "",
  "state": "normal"
}

            

Copying a canvas to the same folder duplicates a canvas.

The conflicts parameter can take one of the following values:

Value	Description
`skip` (default)	Synonym for `cancel`
`cancel`	Cancels the operation if a conflict would happen as a result
`replace`	Replaces the destination canvas with the source one if a conflict happens

Trash Canvas 

Trash a canvas by moving it to the trash folder. Note that conflicts parameter is ignored when moving to trash. You can not move items to other users' trash folder.

             POST /canvases/:id/move

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas to trash
`folder_id`	uuid	yes	The ID of the trash folder

             curl -X POST -H "Private-Token: <access token>" -d '{"folder_id":"trash.1034"}' https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216/move

            

Example response:

             {
  "access": "owner",
  "asset_size": 0,
  "created_at": "2021-10-28T12:27:39.426Z",
  "folder_id": "trash.1034",
  "id": "020b063d-0086-49a5-8dd0-965b8e117216",
  "in_trash": true,
  "mode": "normal",
  "modified_at": "2021-10-28T12:27:39.426Z",
  "name": "Hello",
  "preview_hash": "",
  "state": "normal"
}

            

Delete Canvas 

Permanently deletes a canvas.

             DELETE /canvases/:id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/020b063d-0086-49a5-8dd0-965b8e117216

            

Get Permissions 

Gets the permission overrides on a canvas.

             GET /canvases/:id/permissions

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/permissions

            

Example response:

             {
  "editors_can_share": true,
  "groups": [

  ],
  "link_permission": "none",
  "users": [
    {
      "id": 1034,
      "inherited": false,
      "permission": "owner"
    }
  ]
}

            

Tip

The access field of the /canvas endpoint provides a simple way to find effective permissions of a canvas.

Set Permissions 

Sets permission overrides on a canvas.

             POST /canvases/:id/permissions

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	The ID of the canvas
`editors_can_share`	boolean	no	If true, users with edit access can change permissions
`users`	array	no	The list of users permissions
`groups`	array	no	The list of groups permissions
`link_permission`	string	no	Shared link permission for the canvas

Permission object has the following attributes.

Attribute	Type	Required	Description
`id`	integer	yes	The ID of the user of group
`permission`	string	yes	Permission string

permissions parameter can take one of the following values:

Value	Description
`none`	The principal has no access to the resource
`view`	The principal has read-only access to the resource
`edit`	The principal has edit access to the resource
`owner`	The principal owns the resource

link_permission parameter can take one of the following values:

Value	Description
`none`	Canvas is not shared with link
`view`	Canvas is shared with a link in read-only mode
`edit`	Canvas is shared with a link in read-write mode

             curl -X POST -H "Private-Token: <access token>" -d '{"editors_can_share":false,"link_permission":"view","users":[{"id":100,"permission":"edit"}]}' https://canvus.example.com/api/v1/canvases/9c21f153-ac8b-4ad3-83c5-60c282ee9359/permissions

            

Example response:

             {
  "editors_can_share": false,
  "groups": [

  ],
  "link_permission": "view",
  "users": [
    {
      "id": 100,
      "inherited": false,
      "permission": "edit"
    },
    {
      "id": 1034,
      "inherited": false,
      "permission": "owner"
    }
  ]
}

            

Content from:

Clients API 

The clients API operates on Canvus clients connected to the server.

Note

Clients will not expose themselves for API access by default. This has to be enabled on each client explicitly.

List Clients 

Gets all clients connected to the server.

GET /clients

Attribute	Type	Required	Description
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/clients

            

Example response:

             [
  {
    "access": "rw",
    "id": "e5cad8d4-7051-4051-97bc-13e41fd81ca7",
    "installation_name": "hp-z420",
    "state": "normal",
    "version": "3.0.0 [3837d3aa9]"
  }
]

            

Single Client 

Gets a single client.

             GET /clients/:id

            

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7

            

Example response:

             {
  "access": "rw",
  "id": "e5cad8d4-7051-4051-97bc-13e41fd81ca7",
  "installation_name": "hp-z420",
  "state": "normal",
  "version": "3.0.0 [3837d3aa9]"
}

            

Content from: groups page

Groups API 

API for managing user groups. Read-only for regular users. You must authenticate as an administrator to have write access.

List Groups 

List all user groups.

GET /groups

Attribute	Type	Required	Description
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/groups

            

Example response:

             [
  {
    "description": "All users on this server.",
    "id": 1,
    "name": "All Users"
  },
  {
    "description": "Group for developers",
    "id": 1000,
    "name": "R&D"
  }
]

            

Single Group 

Get a single user group.

             GET /groups/:id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the group
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/groups/1000

            

Example response:

             {
  "description": "Group for developers",
  "id": 1000,
  "name": "R&D"
}

            

Create Group 

Creates a new user group. You must authenticate as an administrator to use this endpoint.

POST /groups

Attribute	Type	Required	Description
`name`	string	yes	Name of the group. Must be unique.
`description`	string	no	Description of the group

             curl -X POST -H "Private-Token: <access token>" -d '{"name":"My group","description":"Test group"}' https://canvus.example.com/api/v1/groups

            

Example response:

             {
  "description": "Test group",
  "id": 1001,
  "name": "My group"
}

            

Delete Group 

Delete a user group. You must authenticate as an administrator to use this endpoint.

             DELETE /groups/:id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the group

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/groups/1001

            

Add User to Group 

Adds a user to the group. You must authenticate as an administrator to use this endpoint.

             POST /groups/:group_id/members

            

Attribute	Type	Required	Description
`group_id` (path)	integer	yes	ID of the group
`id` (path)	integer	yes	User ID

             curl -X POST -H "Private-Token: <access token>" -d '{"id":100}' https://canvus.example.com/api/v1/groups/1000/members

            

List Group Members 

Lists users in the group.

             GET /groups/:id/members

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the group
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/groups/1000/members

            

Example response:

             [
  {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:36:18.817Z",
    "email": "",
    "id": 100,
    "last_login": "2021-07-02T06:37:48.569Z",
    "name": "Guest",
    "state": "normal"
  }
]

            

Remove User from Group 

Removes a user from the group. You must authenticate as an administrator to use this endpoint.

             DELETE /groups/:group_id/members/:user_id

            

Attribute	Type	Required	Description
`group_id` (path)	integer	yes	ID of the group
`user_id` (path)	integer	yes	User ID

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/groups/1000/members/100

            

Content from: images page

Images API 

The images API operates on images on a canvas.

List Images 

Gets all images of the specified canvas.

             GET /canvases/:id/images

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/c3d319c2-5eed-456d-acbb-8da46e788157/images

            

Example response:

             [
  {
    "depth": 0,
    "hash": "cbcb439a796b",
    "id": "40a30897-57ea-4c35-9bf8-64db7fc710e0",
    "location": {
      "x": 5130.68212890625,
      "y": 2164.9775390625
    },
    "original_filename": "",
    "parent_id": "aad4f204-2324-401e-9acf-257d2dad4d99",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 100,
      "width": 100
    },
    "state": "normal",
    "title": "A dog",
    "widget_type": "Image"
  }
]

            

Single Image 

Gets a single image.

             GET /canvases/:id/images/:image_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`image_id` (path)	uuid	yes	ID of the image to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/c3d319c2-5eed-456d-acbb-8da46e788157/images/40a30897-57ea-4c35-9bf8-64db7fc710e0

            

Example response:

             {
  "depth": 0,
  "hash": "cbcb439a796b",
  "id": "40a30897-57ea-4c35-9bf8-64db7fc710e0",
  "location": {
    "x": 5130.68212890625,
    "y": 2164.9775390625
  },
  "original_filename": "",
  "parent_id": "aad4f204-2324-401e-9acf-257d2dad4d99",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A dog",
  "widget_type": "Image"
}

            

Download Image 

Downloads a single image.

             GET /canvases/:id/images/:image_id/download

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`image_id` (path)	uuid	yes	ID of the image to get

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/c3d319c2-5eed-456d-acbb-8da46e788157/images/40a30897-57ea-4c35-9bf8-64db7fc710e0/download

            

Create Image 

Creates an image. The request must be a multipart POST request with an optional json and mandatory data part.

             POST /canvases/:id/images

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`depth`	number	no	Depth of the image compared to its siblings
`location`	object	no	Location of the image relative to its parent
`parent_id`	uuid	no	ID of the image's parent
`pinned`	boolean	no	Is the image pinned or not
`scale`	number	no	Scale of the image
`size`	object	no	Size of the image
`original_filename`	string	no	Original filename of the image
`title`	string	no	Title of the image

             curl -X POST -H "Private-Token: <access token>" -F 'json={"title":"A dog"}' -F 'data=@dog.jpg' https://canvus.example.com/api/v1/canvases/c3d319c2-5eed-456d-acbb-8da46e788157/images

            

Example response:

             {
  "depth": 0,
  "hash": "",
  "id": "0b79a537-e9a6-4733-9610-a4066f49e01f",
  "location": {
    "x": 5226.29150390625,
    "y": 2666.8251953125
  },
  "original_filename": "",
  "parent_id": "aad4f204-2324-401e-9acf-257d2dad4d99",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A dog",
  "widget_type": "Image"
}

            

Update Image 

Updates an image.

             PATCH /canvases/:id/images/:image_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`image_id` (path)	uuid	yes	ID of the image to update
`depth`	number	no	Depth of the image compared to its siblings
`location`	object	no	Location of the image relative to its parent
`parent_id`	uuid	no	ID of the image's parent
`pinned`	boolean	no	Is the image pinned or not
`scale`	number	no	Scale of the image
`size`	object	no	Size of the image
`original_filename`	string	no	Original filename of the image
`title`	string	no	Title of the image

             curl -X PATCH -H "Private-Token: <access token>" -d '{"pinned":true}' https://canvus.example.com/api/v1/canvases/c3d319c2-5eed-456d-acbb-8da46e788157/images/40a30897-57ea-4c35-9bf8-64db7fc710e0

            

Example response:

             {
  "depth": 0,
  "hash": "cbcb439a796b",
  "id": "40a30897-57ea-4c35-9bf8-64db7fc710e0",
  "location": {
    "x": 5130.68212890625,
    "y": 2164.9775390625
  },
  "original_filename": "",
  "parent_id": "aad4f204-2324-401e-9acf-257d2dad4d99",
  "pinned": true,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A dog",
  "widget_type": "Image"
}

            

Delete Image 

Deletes an image.

             DELETE /canvases/:id/images/:image_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`image_id` (path)	uuid	yes	ID of the image to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/c3d319c2-5eed-456d-acbb-8da46e788157/images/40a30897-57ea-4c35-9bf8-64db7fc710e0

            

Content from: license page

License API 

The license API allows managing the Canvus server license. You must authenticate as an administrator to use this endpoint.

Get License Info 

Gets the current license status.

GET /license

Attribute	Type	Required	Description
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/license

            

Example response:

             {
  "edition": "",
  "has_expired": false,
  "is_valid": true,
  "max_clients": -1,
  "type": "",
  "valid_until": "2021-08-17"
}

            

Activate License 

Performs online activation of a new license using an activation key.

             POST /license/activate

            

Attribute	Type	Required	Description
`key`	string	yes	License key

             curl -X POST -H "Private-Token: <access token>" -d '{"key":"AAAA-BBBB-CCCC-DDDD"}' https://canvus.example.com/api/v1/license/activate

            

Offline Activation Request 

Generates an offline activation request.

             GET /license/request

            

Attribute	Type	Required	Description
`key` (query)	string	yes	License key

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/license/request?key=AAAA-BBBB-CCCC-DDDD

            

Install License 

Installs a new license obtained from offline activation.

POST /license

Attribute	Type	Required	Description
`license`	string	yes	License data

             curl -X POST -H "Private-Token: <access token>" -d '{"license":"..."}' https://canvus.example.com/api/v1/license

            

Content from: notes page

Notes API 

The notes API operates on notes on a canvas.

List Notes 

Gets all notes of the specified canvas.

             GET /canvases/:id/notes

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes

            

Example response:

             [
  {
    "background_color": "#ffffff",
    "depth": 0,
    "id": "f77e17a2-3716-46e4-8143-97dde114b20b",
    "location": {
      "x": 3892.455810546875,
      "y": 3326.92041015625
    },
    "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 300,
      "width": 300
    },
    "state": "normal",
    "text": "",
    "title": "",
    "widget_type": "Note"
  }
]

            

Single Note 

Gets a single note.

             GET /canvases/:id/notes/:note_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`note_id` (path)	uuid	yes	ID of the note to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

            

Example response:

             {
  "background_color": "#ffffff",
  "depth": 0,
  "id": "f77e17a2-3716-46e4-8143-97dde114b20b",
  "location": {
    "x": 3892.455810546875,
    "y": 3326.92041015625
  },
  "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 300
  },
  "state": "normal",
  "text": "",
  "title": "",
  "widget_type": "Note"
}

            

Create Note 

Creates a note.

             POST /canvases/:id/notes

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`background_color`	string	no	Color of the note
`depth`	number	no	Depth of the note compared to its siblings
`location`	object	no	Location of the note relative to its parent
`parent_id`	uuid	no	ID of the note's parent
`pinned`	boolean	no	Is the note pinned or not
`scale`	number	no	Scale of the note
`size`	object	no	Size of the note
`text`	string	no	Text in the note
`title`	string	no	Title of the note

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes

            

Example response:

             {
  "background_color": "#ffffff",
  "depth": 0,
  "id": "65110c5c-3dd1-4d71-963e-ae1549fa2f9b",
  "location": {
    "x": 5626.251953125,
    "y": 3265.86328125
  },
  "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 300
  },
  "state": "normal",
  "text": "",
  "title": "",
  "widget_type": "Note"
}

            

Update Note 

Updates a note.

             PATCH /canvases/:id/notes/:note_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`note_id` (path)	uuid	yes	ID of the note to update
`background_color`	string	no	Color of the note
`depth`	number	no	Depth of the note compared to its siblings
`location`	object	no	Location of the note relative to its parent
`parent_id`	uuid	no	ID of the note's parent
`pinned`	boolean	no	Is the note pinned or not
`scale`	number	no	Scale of the note
`size`	object	no	Size of the note
`text`	string	no	Text in the note
`title`	string	no	Title of the note

             curl -X PATCH -H "Private-Token: <access token>" -d '{"text":"I am note"}' https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

            

Example response:

             {
  "background_color": "#ffffff",
  "depth": 0,
  "id": "f77e17a2-3716-46e4-8143-97dde114b20b",
  "location": {
    "x": 3892.455810546875,
    "y": 3326.92041015625
  },
  "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 300
  },
  "state": "normal",
  "text": "I am note",
  "title": "",
  "widget_type": "Note"
}

            

Delete Note 

Deletes a note.

             DELETE /canvases/:id/notes/:note_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`note_id` (path)	uuid	yes	ID of the note to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

            

Content from: pdfs page

PDFs API 

The PDFs API operates on pdfs on a canvas.

List PDFs 

Gets all PDFs of the specified canvas.

             GET /canvases/:id/pdfs

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a528ddb9-ee56-47f2-a419-0c3a9227996e/pdfs

            

Example response:

             [
  {
    "depth": 0,
    "hash": "347b3c308971",
    "id": "d2c53c80-fc5f-4e10-9c8b-28f4a7f06232",
    "index": 1,
    "location": {
      "x": 4629.5146484375,
      "y": 2105.46923828125
    },
    "original_filename": "",
    "parent_id": "0aad755b-c78f-4392-88fb-6efb31d35290",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 100,
      "width": 100
    },
    "state": "normal",
    "title": "A PDF",
    "widget_type": "Pdf"
  }
]

            

Single PDF 

Gets a single PDF.

             GET /canvases/:id/pdfs/:pdf_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`pdf_id` (path)	uuid	yes	ID of the pdf to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a528ddb9-ee56-47f2-a419-0c3a9227996e/pdfs/d2c53c80-fc5f-4e10-9c8b-28f4a7f06232

            

Example response:

             {
  "depth": 0,
  "hash": "347b3c308971",
  "id": "d2c53c80-fc5f-4e10-9c8b-28f4a7f06232",
  "index": 1,
  "location": {
    "x": 4629.5146484375,
    "y": 2105.46923828125
  },
  "original_filename": "",
  "parent_id": "0aad755b-c78f-4392-88fb-6efb31d35290",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A PDF",
  "widget_type": "Pdf"
}

            

Download PDF 

Downloads a single PDF.

             GET /canvases/:id/pdfs/:pdf_id/download

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`pdf_id` (path)	uuid	yes	ID of the pdf to get

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a528ddb9-ee56-47f2-a419-0c3a9227996e/pdfs/d2c53c80-fc5f-4e10-9c8b-28f4a7f06232/download

            

Create PDF 

Creates a PDF. The request must be a multipart POST with an optional json and mandatory data part.

             POST /canvases/:id/pdfs

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`depth`	number	no	Depth of the pdf compared to its siblings
`location`	object	no	Location of the pdf relative to its parent
`parent_id`	uuid	no	ID of the pdf's parent
`pinned`	boolean	no	Is the pdf pinned or not
`scale`	number	no	Scale of the pdf
`size`	object	no	Size of the pdf
`original_filename`	string	no	Original filename of the pdf
`index`	number	no	Currently displayed page of the PDF
`title`	string	no	Title of the pdf

             curl -X POST -H "Private-Token: <access token>" -F 'json={"title":"A PDF"}' -F 'data=@sample.pdf' https://canvus.example.com/api/v1/canvases/a528ddb9-ee56-47f2-a419-0c3a9227996e/pdfs

            

Example response:

             {
  "depth": 0,
  "hash": "",
  "id": "7456c122-cb58-4493-b66e-2efb706e213a",
  "index": 1,
  "location": {
    "x": 3624.74560546875,
    "y": 2387.43798828125
  },
  "original_filename": "",
  "parent_id": "0aad755b-c78f-4392-88fb-6efb31d35290",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A PDF",
  "widget_type": "Pdf"
}

            

Update PDF 

Updates an PDF.

             PATCH /canvases/:id/pdfs/:pdf_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`pdf_id` (path)	uuid	yes	ID of the PDF to update
`depth`	number	no	Depth of the pdf compared to its siblings
`location`	object	no	Location of the pdf relative to its parent
`parent_id`	uuid	no	ID of the pdf's parent
`pinned`	boolean	no	Is the pdf pinned or not
`scale`	number	no	Scale of the pdf
`size`	object	no	Size of the pdf
`original_filename`	string	no	Original filename of the pdf
`index`	number	no	Currently displayed page of the PDF
`title`	string	no	Title of the pdf

             curl -X PATCH -H "Private-Token: <access token>" -d '{"index":2}' https://canvus.example.com/api/v1/canvases/a528ddb9-ee56-47f2-a419-0c3a9227996e/pdfs/d2c53c80-fc5f-4e10-9c8b-28f4a7f06232

            

Example response:

             {
  "depth": 0,
  "hash": "347b3c308971",
  "id": "d2c53c80-fc5f-4e10-9c8b-28f4a7f06232",
  "index": 2,
  "location": {
    "x": 4629.5146484375,
    "y": 2105.46923828125
  },
  "original_filename": "",
  "parent_id": "0aad755b-c78f-4392-88fb-6efb31d35290",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A PDF",
  "widget_type": "Pdf"
}

            

Delete PDF 

Deletes a PDF.

             DELETE /canvases/:id/pdfs/:pdf_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`pdf_id` (path)	uuid	yes	ID of the PDF to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a528ddb9-ee56-47f2-a419-0c3a9227996e/pdfs/d2c53c80-fc5f-4e10-9c8b-28f4a7f06232

            

Content from: server-config page

Server Config API 

The server config API provides access to some of the server settings. Regular or unauthenticated users have read-only access to a limited set of settings.

You must authenticate as an administrator to have read-write access to all settings.

Read Settings 

Gets the server settings. Regular users or unauthenticated requests return only a subset of settings.

GET /server-config

Example of an unauthenticated request:

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

Example response:

             {
  "authentication": {
    "password": {
      "enabled": true,
      "sign_up_enabled": false
    },
    "qr_code": {
      "enabled": true
    },
    "saml": {
      "acs_url": "http://canvus.example.com/users/login/saml/callback",
      "enabled": true,
      "idp_cert_finger_print": "CA:F2:55:F8:F4:6D:E4:24:97:BE:3C:42:AC:CC:BA:41:51:D9:8F:EB:A3:1E:73:77:AB:5C:24:33:A3:5A:20:65",
      "idp_entity_id": "https://samltest.id/saml/idp",
      "idp_target_url": "https://samltest.id/idp/profile/SAML2/Redirect/SSO",
      "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "sign_up_enabled": true,
      "sp_entity_id": "canvus"
    }
  },
  "external_url": "http://canvus.example.com",
  "server_name": ""
}

            

Example of an administrator request:

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/server-config

            

Example response:

             {
  "access": "rw",
  "authentication": {
    "domain_allow_list": [
      "example.com"
    ],
    "password": {
      "enabled": true,
      "sign_up_enabled": false
    },
    "qr_code": {
      "enabled": true
    },
    "require_admin_approval": true,
    "saml": {
      "acs_url": "http://canvus.example.com/users/login/saml/callback",
      "enabled": true,
      "idp_cert_finger_print": "CA:F2:55:F8:F4:6D:E4:24:97:BE:3C:42:AC:CC:BA:41:51:D9:8F:EB:A3:1E:73:77:AB:5C:24:33:A3:5A:20:65",
      "idp_entity_id": "https://samltest.id/saml/idp",
      "idp_target_url": "https://samltest.id/idp/profile/SAML2/Redirect/SSO",
      "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "sign_up_enabled": true,
      "sp_entity_id": "canvus"
    }
  },
  "email": {
    "mail_reply_to_address": "",
    "mail_reply_to_name": "",
    "mail_sender_address": "noreply@example.com",
    "mail_sender_name": "Noreply",
    "smtp_allow_self_signed_certificates": false,
    "smtp_host": "smtp.example.com",
    "smtp_password": "",
    "smtp_port": 25,
    "smtp_security": "none",
    "smtp_username": "noreply@example.com"
  },
  "external_url": "http://canvus.example.com",
  "server_name": ""
}

            

Change Settings 

Sets new values to server settings. You must authenticate as an administrator to access this endpoint.

PATCH /server-config

             curl -X PATCH -H "Private-Token: <access token>" -d '{"authentication":{"domain_allow_list":["example.com"],"password":{"sign_up_enabled":false}}}' https://canvus.example.com/api/v1/server-config

            

Example response:

             {
  "access": "rw",
  "authentication": {
    "domain_allow_list": [
      "example.com"
    ],
    "password": {
      "enabled": true,
      "sign_up_enabled": false
    },
    "qr_code": {
      "enabled": true
    },
    "require_admin_approval": true,
    "saml": {
      "acs_url": "http://canvus.example.com/users/login/saml/callback",
      "enabled": true,
      "idp_cert_finger_print": "CA:F2:55:F8:F4:6D:E4:24:97:BE:3C:42:AC:CC:BA:41:51:D9:8F:EB:A3:1E:73:77:AB:5C:24:33:A3:5A:20:65",
      "idp_entity_id": "https://samltest.id/saml/idp",
      "idp_target_url": "https://samltest.id/idp/profile/SAML2/Redirect/SSO",
      "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "sign_up_enabled": true,
      "sp_entity_id": "canvus"
    }
  },
  "email": {
    "mail_reply_to_address": "",
    "mail_reply_to_name": "",
    "mail_sender_address": "noreply@example.com",
    "mail_sender_name": "Noreply",
    "smtp_allow_self_signed_certificates": false,
    "smtp_host": "smtp.example.com",
    "smtp_password": "",
    "smtp_port": 25,
    "smtp_security": "none",
    "smtp_username": "noreply@example.com"
  },
  "external_url": "http://canvus.example.com",
  "server_name": ""
}

            

Send Test Email 

Sends a test email to the email address of the user making the request. You must authenticate as an administrator to access this endpoint.

             POST /server-config/send-test-email

            

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/server-config/send-test-email

            

Content from:

Server Info 

Retrieve information for this Canvus Server instance.

GET /server-info

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

Example response:

            {
  "api": [
    "v1.1"
  ],
  "go": "1.16.4",
  "server_id": "71ac3376-5020-4033-a159-71c213dc9be6",
  "version": "3.0.0 [3837d3aa9]"
}

           

Content from: uploads-folder page

Uploads Folder API 

Allows content to be uploaded to the Uploads folder of a specific canvas.

Upload a Note 

Creates a new note inside the uploads folder. The request must be a multipart POST request with a single json part.

             POST /canvases/:id/uploads-folder

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`upload_type`	string	yes	Must be equal to `note`
`background_color`	string	no	Color of the note
`text`	string	no	Text in the note
`title`	string	no	Title of the note

             curl -X POST -H "Private-Token: <access token>" -F 'json={"upload_type":"note","text":"Hello, world","title":"Hello, world"}' https://canvus.example.com/api/v1/canvases/863e7a77-0874-4170-9a0c-7f65d7869c37/uploads-folder

            

Example response:

             {
  "background_color": "#ffffff",
  "depth": 0,
  "id": "content",
  "location": {
    "x": 0,
    "y": 0
  },
  "parent_id": "99a81a8b-9605-4122-a233-8de3a03a3f05",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 300
  },
  "state": "normal",
  "text": "Hello, world",
  "title": "Hello, world",
  "widget_type": "Note"
}

            

Upload a File 

Creates a new file asset inside the uploads folder. You can upload PDFs, images, videos and other files. The asset type is automatically recognized by Canvus and you don't need to specify it through the API. Unrecognized file types are uploaded as generic assets.

The request must be a multipart POST request with an optional json and mandatory data part.

             POST /canvases/:id/uploads-folder

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`upload_type`	string	no	Must be missing, empty or equal to `asset`
`original_filename`	string	no	Original filename
`title`	string	no	Title of the asset

             curl -X POST -H "Private-Token: <access token>" -F 'json={"upload_type":"asset","title":"My video"}' -F 'data=@SampleVideo_1280x720_1mb.mp4' https://canvus.example.com/api/v1/canvases/863e7a77-0874-4170-9a0c-7f65d7869c37/uploads-folder

            

Example response:

             {
  "depth": 0,
  "hash": "",
  "id": "content",
  "location": {
    "x": 0,
    "y": 0
  },
  "original_filename": "",
  "parent_id": "b491c355-1bcc-48ff-be30-6df65d6e1ed4",
  "pinned": false,
  "playback_position": 0,
  "playback_state": "STOPPED",
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "My video",
  "widget_type": "Video"
}

            

Content from: users page

Users API 

The users API provides access to user accounts on the server.

Regular users can list other users, change their own profile data (such as name, password, etc.) or block themselves. Administrators can modify other users, create new user accounts and execute admin-only tasks such as approving new users.

Note

Group membership for users is managed through Groups API .

List Users 

Gets a list of all users.

GET /users

Attribute	Type	Required	Description
`subscribe` (query)	boolean	no	See Streaming

curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users

Example response:

             [
  {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:36:18.817Z",
    "email": "",
    "id": 100,
    "last_login": "2021-07-02T06:37:48.569Z",
    "name": "Guest",
    "state": "normal"
  },
  {
    "admin": true,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:36:33.392Z",
    "email": "admin@example.com",
    "id": 1000,
    "last_login": "2021-07-02T06:38:36.549Z",
    "name": "admin",
    "state": "normal"
  },
  {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:38:37.141Z",
    "email": "alice@example.com",
    "id": 1002,
    "last_login": "",
    "name": "Alice",
    "state": "normal"
  }
]

            

Single User 

Gets info about a single user.

             GET /users/:id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "",
  "name": "Alice",
  "state": "normal"
}

            

Create User 

Creates a new user. You must authenticate as an administrator to use this endpoint.

Tip

Unauthenticated requests can be made to the Register User endpoint.

POST /users

Attribute	Type	Required	Description
`email`	string	yes	Email (used also as the login name) of the user. Email address have to be unique for each user.
`name`	string	yes	Display name of the user
`password`	string	no	Password of the user. If password is missing the server sends password reset email to the user
`admin`	boolean	no	If true, the new user is admin. By default this is false.
`approved`	boolean	no	If true, the new user is initially approved . Default value depends on the server settings
`blocked`	boolean	no	If true, the new user is initially blocked . By default this is false.

             curl -X POST -H "Private-Token: <access token>" -d '{"email":"bob@example.com","password":"BBBB","name":"Bob"}' https://canvus.example.com/api/v1/users

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.501Z",
  "email": "bob@example.com",
  "id": 1003,
  "last_login": "",
  "name": "Bob",
  "state": "normal"
}

            

Delete User 

Permanently deletes a user. You must authenticate as an administrator to use this endpoint.

             DELETE /users/:id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	The ID of the user to get

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1003

            

Register User 

Registers a new user account. This endpoint does not require authentication.

On success, this endpoint will send an email with confirmation token to the provided email address.

The new user account is not active until the email address is confirmed.

Tip

Registering new users can be disabled in the server settings .

             POST /users/register

            

Attribute	Type	Required	Description
`email`	string	yes	Email (used also as the login name) of the user. Email address have to be unique for each user.
`name`	string	yes	Display name of the user
`password`	string	yes	Password of the user
`admin`	boolean	no	If true, the new user is admin. By default this is false. Only admin user can set it to true.
`approved`	boolean	no	Is the user needs approval ? Default value depends on the server settings . Only admin user can explicitly set it to true.
`blocked`	boolean	no	If true, the new user is initially blocked. By default this is false.

             curl -X POST -d '{"email":"carol@example.com","password":"CCCC","name":"Carol"}' https://canvus.example.com/api/v1/users/register

            

Example response:

             {
  "msg": "Sign-up using a password is not enabled"
}

            

Approve User 

Approves registered user accounts pending approval. You must authenticate as an administrator to use this endpoint.

             POST /users/:id/approve

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the user

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002/approve

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "",
  "name": "Alice",
  "state": "normal"
}

            

Email Confirmation 

Confirms user email address with the token from email. This endpoint does not require authentication.

             POST /users/confirm-email

            

Attribute	Type	Required	Description
`token`	string	yes	Token from the email

             curl -X POST -d '{"token":"AAAAAAAAAAAAAAA"}' https://canvus.example.com/api/v1/users/confirm-email

            

Example response:

             {
  "msg": "Invalid email confirmation token."
}

            

Change Password 

This endpoint allows regular user to change their own password by providing the current and new password.

Administrators can use this endpoint to change passwords of other regular users.

             POST /users/:id/password

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the user
`current_password`	string	yes	Old password
`new_password`	string	yes	New password

             curl -X POST -H "Private-Token: <access token>" -d '{"current_password":"AAAA","new_password":"BBBB"}' https://canvus.example.com/api/v1/users/1002/password

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "",
  "name": "Alice",
  "state": "normal"
}

            

Request Password Reset 

Sends an email with a password reset token to the email address of the user making the request.

The emailed token must be confirmed through the reset endpoint. This endpoint does not require authentication.

             POST /users/password/create-reset-token

            

Attribute	Type	Required	Description
`email`	string	yes	Email of the user

             curl -X POST -d '{"email":"bob@example.com"}' https://canvus.example.com/api/v1/users/password/create-reset-token

            

Validate Password Reset Token 

Validates a password reset token, but does not consume it. This endpoint is available without authentication.

             GET /users/password/validate-reset-token

            

Attribute	Type	Required	Description
`token` (query)	string	yes	Token from the email

             curl https://canvus.example.com/api/v1/users/password/validate-reset-token?token=AAAAAAAAAAAAAAA

            

Example response:

             {
  "msg": "Invalid token"
}

            

Reset Password 

Resets a user password using the provided token from password reset email. This endpoint is available without authentication.

             POST /users/password/reset

            

Attribute	Type	Required	Description
`token`	string	yes	Token from the email
`password`	string	yes	New password

             curl -X POST -d '{"token":"AAAAAAAAAAAAAAA","password":"DDDD"}' https://canvus.example.com/api/v1/users/password/reset

            

Example response:

             {
  "msg": "Invalid token"
}

            

Sign In User 

Signs the user in and issues an access token. This endpoint is available without authentication.

             POST /users/login

            

Attribute	Type	Required	Description
`email`	string	yes	User email
`password`	string	yes	User password

             curl -X POST -d '{"email":"alice@example.com","password":"BBBB"}' https://canvus.example.com/api/v1/users/login

            

Example response:

             {
  "token": "lmFU9obmM5v4o6jdCXsRW6v5bLD9w47aGIP4eMRnf3A",
  "user": {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:38:37.141Z",
    "email": "alice@example.com",
    "id": 1002,
    "last_login": "",
    "name": "Alice",
    "state": "normal"
  }
}

            

Alternatively this endpoint can validate an existing token. If token is valid the token lifetime is prolonged.

Attribute	Type	Required	Description
`token`	string	yes	Access token

             curl -X POST -d '{"token":"z_Ttm-tcFpiadMUR2A_8kQnkOsl6wmcEKplotULC9fk"}' https://canvus.example.com/api/v1/users/login

            

Example response:

             {
  "token": "n8_ZgoRHKnQWJnxdgT7s12jfWH5VGuNzpnps3PGZzwo",
  "user": {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:38:37.141Z",
    "email": "alice@example.com",
    "id": 1002,
    "last_login": "2021-07-02T06:38:38.722Z",
    "name": "Alice",
    "state": "normal"
  }
}

            

Sign Out User 

Signs the user out by invalidating the provided access token.

             POST /users/logout

            

Attribute	Type	Required	Description
`token`	string	no	Token to invalidate. If empty the `Private-Token` is used.

             curl -X POST -H "Private-Token: <access token>" -d '{"token":"z_Ttm-tcFpiadMUR2A_8kQnkOsl6wmcEKplotULC9fk"}' https://canvus.example.com/api/v1/users/logout

            

Block a User 

Blocks a user. Blocked users can not sign in. Regular users can only block their own account. Administrators can block any user.

             POST /users/:id/block

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the user

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002/block

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": true,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "2021-07-02T06:38:38.744Z",
  "name": "Alice",
  "state": "normal"
}

            

Unblock a User 

Unblocks a user. You must authenticate as an administrator to use this endpoint.

             POST /users/:id/unblock

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the user

             curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002/unblock

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "2021-07-02T06:38:38.744Z",
  "name": "Alice",
  "state": "normal"
}

            

Set User Info 

Changes user profile data such as name or email. Regular users can change only their own profile and only certain fields, administrators can change all fields of any user.

             PATCH /users/:id

            

Attribute	Type	Required	Description
`id` (path)	integer	yes	ID of the user
`email`	string	no	Email (used also as the login name) of the user. Email address have to be unique for each user.
`name`	string	no	Display name of the user
`password`	string	no	Password of the user. Admin-only.
`admin`	boolean	no	If true, the user is admin. Admin-only.
`approved`	boolean	no	If true, the user is approved. This can be changed only from false to true. Admin-only.
`blocked`	boolean	no	If true, the user is blocked.
`need_email_confirmation`	boolean	no	If true the user has confirmed email. This can be changed only from false to true. Admin-only.

             curl -X PATCH -H "Private-Token: <access token>" -d '{"name":"Alice Cooper"}' https://canvus.example.com/api/v1/users/1002

            

Example response:

             {
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "2021-07-02T06:38:38.744Z",
  "name": "Alice Cooper",
  "state": "normal"
}

            

SAML 2.0 Sign-in 

Implements SAML 2.0 ACS endpoint. Validates a SAML assertion and on success signs in the user and issues access token. SAML sign-in can be disabled in server settings . This endpoint is available without authentication.

             POST /users/login/saml

            

Attribute	Type	Required	Description
`inResponseTo`	string	yes	Cookie known to the initiator of the request
`responseXml`	string	yes	SAML assertion XML

Content from: videos page

Videos API 

The videos API operates on videos on a canvas.

List Videos 

Gets all videos of the specified canvas.

             GET /canvases/:id/videos

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a8b5ed9e-6e57-41c8-96cb-be4aec4bfd03/videos

            

Example response:

             [
  {
    "depth": 0,
    "hash": "863b0937ee95",
    "id": "105a8486-ac84-49f9-a487-763279a6f658",
    "location": {
      "x": 3737.212646484375,
      "y": 2311.91357421875
    },
    "original_filename": "",
    "parent_id": "34f8909a-6736-49f9-9027-7f7cab5c1acf",
    "pinned": false,
    "playback_position": 0,
    "playback_state": "STOPPED",
    "scale": 1,
    "size": {
      "height": 100,
      "width": 100
    },
    "state": "normal",
    "title": "A video",
    "widget_type": "Video"
  }
]

            

Single Video 

Gets a single video.

             GET /canvases/:id/videos/:video_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`video_id` (path)	uuid	yes	ID of the video to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a8b5ed9e-6e57-41c8-96cb-be4aec4bfd03/videos/105a8486-ac84-49f9-a487-763279a6f658

            

Example response:

             {
  "depth": 0,
  "hash": "863b0937ee95",
  "id": "105a8486-ac84-49f9-a487-763279a6f658",
  "location": {
    "x": 3737.212646484375,
    "y": 2311.91357421875
  },
  "original_filename": "",
  "parent_id": "34f8909a-6736-49f9-9027-7f7cab5c1acf",
  "pinned": false,
  "playback_position": 0,
  "playback_state": "STOPPED",
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A video",
  "widget_type": "Video"
}

            

Download Video 

Downloads a single video.

             GET /canvases/:id/videos/:video_id/download

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`video_id` (path)	uuid	yes	ID of the video to get

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a8b5ed9e-6e57-41c8-96cb-be4aec4bfd03/videos/105a8486-ac84-49f9-a487-763279a6f658/download

            

Create Video 

Creates a video. The request must be a multipart POST request with an optional json and mandatory data part.

             POST /canvases/:id/videos

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`depth`	number	no	Depth of the video compared to its siblings
`location`	object	no	Location of the video relative to its parent
`parent_id`	uuid	no	ID of the video's parent
`pinned`	boolean	no	Is the video pinned or not
`scale`	number	no	Scale of the video
`size`	object	no	Size of the video
`original_filename`	string	no	Original filename of the video
`title`	string	no	Title of the video
`playback_state`	string	no	`stopped` , `playing` or `paused`
`playback_position`	number	no	Current playback position in seconds

             curl -X POST -H "Private-Token: <access token>" -F 'json={"title":"A video"}' -F 'data=@SampleVideo_1280x720_1mb.mp4' https://canvus.example.com/api/v1/canvases/a8b5ed9e-6e57-41c8-96cb-be4aec4bfd03/videos

            

Example response:

             {
  "depth": 0,
  "hash": "",
  "id": "370b112b-c6e9-440f-bdad-f6d6cf6a6d9f",
  "location": {
    "x": 5148.7529296875,
    "y": 2807.719970703125
  },
  "original_filename": "",
  "parent_id": "34f8909a-6736-49f9-9027-7f7cab5c1acf",
  "pinned": false,
  "playback_position": 0,
  "playback_state": "STOPPED",
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A video",
  "widget_type": "Video"
}

            

Update Video 

Updates a video.

             PATCH /canvases/:id/videos/:video_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`video_id` (path)	uuid	yes	ID of the video to update
`depth`	number	no	Depth of the video compared to its siblings
`location`	object	no	Location of the video relative to its parent
`parent_id`	uuid	no	ID of the video's parent
`pinned`	boolean	no	Is the video pinned or not
`scale`	number	no	Scale of the video
`size`	object	no	Size of the video
`original_filename`	string	no	Original filename of the video
`title`	string	no	Title of the video
`playback_state`	string	no	`stopped` , `playing` or `paused`
`playback_position`	number	no	Current playback position in seconds

             curl -X PATCH -H "Private-Token: <access token>" -d '{"title":"Sample"}' https://canvus.example.com/api/v1/canvases/a8b5ed9e-6e57-41c8-96cb-be4aec4bfd03/videos/105a8486-ac84-49f9-a487-763279a6f658

            

Example response:

             {
  "depth": 0,
  "hash": "863b0937ee95",
  "id": "105a8486-ac84-49f9-a487-763279a6f658",
  "location": {
    "x": 3737.212646484375,
    "y": 2311.91357421875
  },
  "original_filename": "",
  "parent_id": "34f8909a-6736-49f9-9027-7f7cab5c1acf",
  "pinned": false,
  "playback_position": 0,
  "playback_state": "STOPPED",
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "Sample",
  "widget_type": "Video"
}

            

Delete Video 

Deletes a video.

             DELETE /canvases/:id/videos/:video_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`video_id` (path)	uuid	yes	ID of the video to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/a8b5ed9e-6e57-41c8-96cb-be4aec4bfd03/videos/105a8486-ac84-49f9-a487-763279a6f658

            

Content from: widgets page

Widgets API 

The widgets API provides a uniform read-only access to canvas items regardless of their type.

List Widgets 

Gets all widgets of the specified canvas.

             GET /canvases/:id/widgets

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/3ad9ece4-28be-4e19-9f9a-1a01a4dbae28/widgets

            

Example response:

             [
  {
    "depth": 0,
    "id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "location": {
      "x": 0,
      "y": 0
    },
    "parent_id": "",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 5400,
      "width": 9600
    },
    "state": "normal",
    "widget_type": "SharedCanvas"
  },
  {
    "depth": 0,
    "hash": "cbcb439a796b",
    "id": "2a59b935-02b6-47dc-820c-caab1de64247",
    "location": {
      "x": 5291.89892578125,
      "y": 2564.220703125
    },
    "original_filename": "",
    "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 100,
      "width": 100
    },
    "state": "normal",
    "title": "A dog",
    "widget_type": "Image"
  },
  {
    "background_color": "#ffffff",
    "depth": 0,
    "id": "dc3ca5b6-0fb4-4628-bf4e-2008087b9430",
    "location": {
      "x": 5997.61376953125,
      "y": 3253.6298828125
    },
    "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 300,
      "width": 300
    },
    "state": "normal",
    "text": "",
    "widget_type": "Note"
  }
]

            

Single Widget 

Gets a single widget.

             GET /canvases/:id/widgets/:widget_id

            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`widget_id` (path)	uuid	yes	ID of the item to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/3ad9ece4-28be-4e19-9f9a-1a01a4dbae28/widgets/2a59b935-02b6-47dc-820c-caab1de64247

            

Example response:

             {
  "depth": 0,
  "hash": "cbcb439a796b",
  "id": "2a59b935-02b6-47dc-820c-caab1de64247",
  "location": {
    "x": 5291.89892578125,
    "y": 2564.220703125
  },
  "original_filename": "",
  "parent_id": "eab4c3da-0fc3-46f2-a7a7-bf9d16494348",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 100,
    "width": 100
  },
  "state": "normal",
  "title": "A dog",
  "widget_type": "Image"
}

            

Content from: workspaces page

Workspaces API 

The workspaces API operates on the workspaces on a client.

List Workspaces 

Gets all workspaces of the specified client.

             GET /clients/:client_id/workspaces

            

Attribute	Type	Required	Description
`client_id` (path)	uuid	yes	ID of the client
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces

            

Example response:

             [
  {
    "canvas_id": "df172fda-5e85-4b5c-b602-2eda5a6602f1",
    "canvas_size": {
      "height": 5400,
      "width": 9600
    },
    "index": 0,
    "info_panel_visible": true,
    "location": {
      "x": 0,
      "y": 0
    },
    "pinned": false,
    "server_id": "71ac3376-5020-4033-a159-71c213dc9be6",
    "size": {
      "height": 1080,
      "width": 1271
    },
    "state": "normal",
    "user": "guest",
    "view_rectangle": {
      "height": 648,
      "width": 762.5999755859375,
      "x": -2244.5,
      "y": -1080.0001220703125
    },
    "workspace_name": "Workspace 1",
    "workspace_state": "open"
  },
  {
    "canvas_id": "",
    "index": 1,
    "info_panel_visible": true,
    "location": {
      "x": 1271,
      "y": 0
    },
    "pinned": false,
    "server_id": "",
    "size": {
      "height": 1080,
      "width": 649
    },
    "state": "normal",
    "user": "",
    "view_rectangle": {
      "height": 648,
      "width": 389.400146484375,
      "x": -3191,
      "y": -1080.0001220703125
    },
    "workspace_name": "Workspace 2",
    "workspace_state": "canvas_list"
  }
]

            

Single Workspace 

Gets a single workspace.

             GET /clients/:client_id/workspaces/:workspace_index

            

Attribute	Type	Required	Description
`client_id` (path)	uuid	yes	ID of the client
`workspace_index` (path)	number	yes	Index of the workspace to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0

            

Example response:

             {
  "canvas_id": "df172fda-5e85-4b5c-b602-2eda5a6602f1",
  "canvas_size": {
    "height": 5400,
    "width": 9600
  },
  "index": 0,
  "info_panel_visible": true,
  "location": {
    "x": 0,
    "y": 0
  },
  "pinned": false,
  "server_id": "71ac3376-5020-4033-a159-71c213dc9be6",
  "size": {
    "height": 1080,
    "width": 1271
  },
  "state": "normal",
  "user": "guest",
  "view_rectangle": {
    "height": 648,
    "width": 762.5999755859375,
    "x": -2244.5,
    "y": -1080.0001220703125
  },
  "workspace_name": "Workspace 1",
  "workspace_state": "open"
}

            

Update Workspace 

Changes some of the workspace parameters such as viewport location. For opening a new canvas use open canvas endpoint.

             PATCH /clients/:client_id/workspaces/:workspace_index

            

Attribute	Type	Required	Description
`client_id` (path)	uuid	yes	ID of the client
`workspace_index` (path)	number	yes	Index of the workspace to update
`info_panel_visible`	boolean	no	Is the workspace info panel visible
`pinned`	boolean	no	Is the workspace pinned
`view_rectangle`	object	no	The visible rectangle in canvas coordinates

             curl -X PATCH -H "Private-Token: <access token>" -d '{"pinned":"false"}' https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0

            

Example response:

             {
  "canvas_id": "df172fda-5e85-4b5c-b602-2eda5a6602f1",
  "canvas_size": {
    "height": 5400,
    "width": 9600
  },
  "index": 0,
  "info_panel_visible": true,
  "location": {
    "x": 0,
    "y": 0
  },
  "pinned": false,
  "server_id": "71ac3376-5020-4033-a159-71c213dc9be6",
  "size": {
    "height": 1080,
    "width": 1271
  },
  "state": "normal",
  "user": "guest",
  "view_rectangle": {
    "height": 648,
    "width": 762.5999755859375,
    "x": -2244.5,
    "y": -1080.0001220703125
  },
  "workspace_name": "Workspace 1",
  "workspace_state": "open"
}

            

Open Canvas 

Tries to open a specified canvas on the workspace.

You can open canvases from other servers assuming you know the server ID . This endpoint does not report errors from the client side. If the request passes basic data validation the status code is 200 OK .

You should monitor workspace state to find out whether or not the request actually succeeded.

             POST /clients/:client_id/workspaces/:workspace_index/open-canvas

            

Attribute	Type	Required	Description
`client_id` (path)	uuid	yes	ID of the client
`workspace_index` (path)	number	yes	Index of the workspace
`canvas_id`	uuid	yes	ID of the canvas to open
`server_id`	uuid	no	Server ID where this canvas is located
`user_email`	string	no	The user on whose behalf the canvas is opened

Possible values for the user_email parameter:

Value	Description
Email address	User with specified email. If necessary the log-in dialog will prompt on the client.
Empty string (or missing parameter)	Current workspace user
`guest`	Guest user

Possible values for the server_id parameter:

Value	Description
ID	Server with the ID. This server should be configured on the client and be online.
`internal`	Local server
Empty string (or missing parameter)	Synonym for `internal`

             curl -X POST -H "Private-Token: <access token>" -d '{"canvas_id":"df172fda-5e85-4b5c-b602-2eda5a6602f1","server_id":"71ac3376-5020-4033-a159-71c213dc9be6"}' https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0/open-canvas

            

Content from: connectors page

Connectors API

The connectors API operates on connectors between widgets on a canvas. The set of connectors is a property of the canvas, not individual widgets.

List Connectors

Gets all connectors of the specified canvas.

             GET /canvases/:id/connectors
            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/connectors
            

Example response:

             [
      {
        "dst": {
            "auto_location": false,
            "id": "e7d6848e-a14d-49b4-9b06-4a43a3280de8",
            "rel_location": {
                "x": 1,
                "y": 0.5
            },
            "tip": "solid-equilateral-triangle"
        },
        "id": "0dd40875-e538-4742-802f-0e186fee27a9",
        "line_color": "#e7e7f2ff",
        "line_width": 5,
        "src": {
            "auto_location": false,
            "id": "77dd677a-e72f-46e2-bb55-a096371d0034",
            "rel_location": {
                "x": 1,
                "y": 0.5
            },
            "tip": "none"
        },
        "state": "normal",
        "type": "curve",
        "widget_type": "Connector"
    },
    {
        "dst": {
            "auto_location": false,
            "id": "77dd677a-e72f-46e2-bb55-a096371d0034",
            "rel_location": {
                "x": 0,
                "y": 0.5
            },
            "tip": "solid-equilateral-triangle"
        },
        "id": "987e23f6-09f1-409a-9c1b-bc49dd59b460",
        "line_color": "#e7e7f2ff",
        "line_width": 5,
        "src": {
            "auto_location": false,
            "id": "cc79d750-bb93-4ebb-9900-ee12ae4e4de2",
            "rel_location": {
                "x": 0,
                "y": 0.5
            },
            "tip": "none"
        },
        "state": "normal",
        "type": "curve",
        "widget_type": "Connector"
    }
]
            

Note: The "type" field currently only supports "curve" value in Canvus 3.2, but may be extended in future versions.

Single Connector

Gets a single connector.

             GET /canvases/:id/connectors/:connector_id
            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`connector_id` (path)	uuid	yes	ID of the connector to get
`subscribe` (query)	boolean	no	See Streaming

             curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/connectors/f77e17a2-3716-46e4-8143-97dde114b20b
            

Example response:

             {
        "dst": {
            "auto_location": false,
            "id": "77dd677a-e72f-46e2-bb55-a096371d0034",
            "rel_location": {
                "x": 0,
                "y": 0.5
            },
            "tip": "solid-equilateral-triangle"
        },
        "id": "987e23f6-09f1-409a-9c1b-bc49dd59b460",
        "line_color": "#e7e7f2ff",
        "line_width": 5,
        "src": {
            "auto_location": false,
            "id": "cc79d750-bb93-4ebb-9900-ee12ae4e4de2",
            "rel_location": {
                "x": 0,
                "y": 0.5
            },
            "tip": "none"
        },
        "state": "normal",
        "type": "curve",
        "widget_type": "Connector"
    }
            

Create Connector

Creates a new connector between widgets.

             POST /canvases/:id/connectors
            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`src`	object	yes	Source widget connection details
`dst`	object	yes	Destination widget connection details
`type`	string	no	Type of connector (currently only "curve" supported)

The src and dst objects have the following fields:

id (uuid, required) - ID of the widget
rel-location (object, required) - x,y coordinates [0..1] for connection point
auto-location (boolean, optional) - Whether location updates automatically
tip (string, optional) - Connector tip style ("none" or "triangle")

             curl -X POST -H "Private-Token: <access token>" -d @connector.json https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/connectors
            

Example request body:

             {
  "src": {
    "id": "8b57fb06-981e-4f55-8c0a-b70a25ba8140",
    "rel-location": {
      "x": 0,
      "y": 0.5
    },
    "auto-location": false,
    "tip": "none"
  },
  "dst": {
    "id": "d7c4d3c0-b372-421b-8aaa-cac619e8f7f6", 
    "rel-location": {
      "x": 1,
      "y": 0.5
    },
    "auto-location": false,
    "tip": "triangle"
  }
}
            

Update Connector

Updates an existing connector.

             PATCH /canvases/:id/connectors/:connector_id
            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`connector_id` (path)	uuid	yes	ID of the connector to update

             curl -X PATCH -H "Private-Token: <access token>" -d @update.json https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/connectors/f77e17a2-3716-46e4-8143-97dde114b20b
            

Example request body:

             {
  "src": {
    "rel-location": {
      "x": 0.3,
      "y": 1
    }
  }
}
            

Delete Connector

Deletes a connector.

             DELETE /canvases/:id/connectors/:connector_id
            

Attribute	Type	Required	Description
`id` (path)	uuid	yes	ID of the canvas
`connector_id` (path)	uuid	yes	ID of the connector to delete

             curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/connectors/f77e17a2-3716-46e4-8143-97dde114b20b
            

Content from: changelog page

v1.2 

Added unauthenticated access for link-shared canases and link_permission attribute to the permissions endpoint.

Added /uploads-folder endpoint.

Added /send-test-email endpoint.

Added title parameter for Notes.

Filter out the ID of the currently open canvas in the Client API if the user who makes the request doesn't have access to that canvas.

Added server_name attribute to the /server-config .

v1.1 

Removed ini file tokens, made authentication mandatory for the most endpoints.

Added /login , login/saml and /logout endpoints.

Added users and groups management API.

Added /permissions endpoints for canvases and folders.

Added DELETE /children for folders.

Added mode (demo or normal) attribute for canvases.

Added /save and /restore endpoints for canvases.

Added /preview for canvases.

Added API tokens management API.

Added license management API.

Added audit log API.

Added /server-config endpoint.

Applied permissions model to the Client API.

Added /open-canvas endpoint for workspaces.

Added user-email and server-id attributes to the /workspace .