Skip to content

Canvas Folders

Canvas folders organize canvases into a hierarchical directory structure on the Canvus server. Every user has a home folder and a trash folder. Canvases and subfolders live inside these folders, forming a tree.

The folder hierarchy works like a filesystem:

  • There is a single root folder at the top (empty name, no parent)
  • Each user gets a home folder directly under the root
  • Each user's home folder contains a trash folder (ID format: trash.<user-id>)
  • Users can create subfolders to any depth inside their home folder
  • Permissions cascade from parent folders to children unless explicitly overridden

All endpoints below are prefixed with /api/v1.

Authentication

All folder endpoints require a Private-Token header containing a valid API access token.

Private-Token: YOUR_TOKEN

Streaming (Long-Polling)

GET endpoints that list streaming as supported accept a ?subscribe query parameter. When present, the server holds the connection open and streams JSON updates as newline-delimited JSON. See the Streaming documentation for details.

Folder Object

Every folder returned by the API includes these fields:

  • id (string) -- unique identifier for the folder. User home folders use numeric IDs (e.g., "1000"). Trash folders use the format "trash.<user-id>" (e.g., "trash.1000"). Subfolders use UUIDs.
  • name (string) -- display name of the folder. The root folder has an empty name. Trash folders are named "Trash".
  • folder_id (string) -- ID of the parent folder. The root folder has an empty string.
  • access (string) -- the requesting user's effective permission on this folder (owner, edit, view, none)
  • state (string) -- folder state (normal)
  • in_trash (boolean) -- whether the folder is currently in the trash

List Folders

Returns all folders visible to the authenticated user. The response includes the root folder, user home folders, trash folders, and any subfolders the user can access.

GET /api/v1/canvas-folders
  • Authentication: Required
  • Streaming: Supported

Query parameters:

  • subscribe (boolean, optional) -- enable streaming

curl example:

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

Response: 200 OK

[
  {
    "access": "edit",
    "folder_id": "",
    "id": "4f517d91-7448-4810-87f2-f6b25e8dc3cd",
    "in_trash": false,
    "name": "",
    "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": "Projects",
    "state": "normal"
  },
  {
    "access": "edit",
    "folder_id": "4f517d91-7448-4810-87f2-f6b25e8dc3cd",
    "id": "100",
    "in_trash": false,
    "name": "Guest",
    "state": "normal"
  }
]

In this example, the folder tree looks like:

  • (root) 4f517d91-...
  • admin 1000
    • Trash trash.1000
    • Projects b574c9f9-...
  • Guest 100

Error responses:

  • 401 Unauthorized -- missing or invalid token

Get a Single Folder

Returns details for one folder.

GET /api/v1/canvas-folders/:folder_id
  • Authentication: Required
  • Streaming: Supported

Path parameters:

  • folder-id (string, required) -- the folder ID

Query parameters:

  • subscribe (boolean, optional) -- enable streaming

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3

Response: 200 OK

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

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 404 Not Found -- folder does not exist

Create a Folder

Creates a new subfolder. If no folder_id is specified, the folder is created in the authenticated user's home folder.

POST /api/v1/canvas-folders
  • Authentication: Required
  • Streaming: Not supported

Request body (JSON):

  • name (string, optional) -- name for the new folder
  • folder_id (string, optional) -- ID of the parent folder

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 Workshops", "folder_id": "b574c9f9-2717-4c95-b6dd-c48d146c28f3"}' \
  https://canvus.example.com/api/v1/canvas-folders

Response: 200 OK

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

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions on parent folder
  • 404 Not Found -- parent folder does not exist

Rename a Folder

Changes the display name of a folder.

PATCH /api/v1/canvas-folders/:folder_id
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder ID

Request body (JSON):

  • name (string, optional) -- new name for the folder

curl example:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q2 Workshops"}' \
  https://canvus.example.com/api/v1/canvas-folders/293bddf1-8e0e-4306-823e-19e5be9b2349

Response: 200 OK

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

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- folder does not exist

Delete a Folder

Permanently deletes a folder and all of its contents (subfolders and canvases). This action is irreversible. To move a folder to the trash instead, see Trash a Folder.

DELETE /api/v1/canvas-folders/:folder_id
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder ID

curl example:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvas-folders/293bddf1-8e0e-4306-823e-19e5be9b2349

Response: 200 OK (empty body)

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- folder does not exist

Delete Folder Contents

Deletes all children of a folder (subfolders and canvases) without deleting the folder itself. This is commonly used to empty the trash.

DELETE /api/v1/canvas-folders/:folder_id/children
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder ID

curl example:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvas-folders/trash.1000/children

Response: 200 OK (empty body)

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- folder does not exist

Move Folder

Moves a folder (and all its contents) into a different parent folder. If the destination already contains a folder with the same name, the folders are merged -- their contents are combined into a single folder.

Both POST and PATCH methods are accepted for this endpoint.

POST /api/v1/canvas-folders/:folder_id/move
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder to move

Request body (JSON):

  • folder_id (string, required) -- the destination parent folder ID
  • conflicts (string, optional) -- conflict resolution strategy (default: skip)

Conflict resolution values:

  • skip -- skip conflicting items (default)
  • cancel -- cancel the entire operation if any conflict would occur
  • replace -- replace conflicting items in the destination

curl example:

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

Response: 200 OK

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

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions on source or destination
  • 404 Not Found -- folder does not exist
  • 409 Conflict -- name conflict and conflicts is cancel

Copy Folder

Copies a folder (and all its contents) into a different parent folder. If the destination already contains a folder with the same name, the folders are merged. The one exception is copying a folder to its own parent, which creates a duplicate.

Both POST and PATCH methods are accepted for this endpoint.

POST /api/v1/canvas-folders/:folder_id/copy
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder to copy

Request body (JSON):

  • folder_id (string, required) -- the destination parent folder ID
  • conflicts (string, optional) -- conflict resolution strategy (default: skip)

Conflict resolution values:

  • skip -- skip conflicting items (default)
  • cancel -- cancel the entire operation if any conflict would occur
  • replace -- replace conflicting items in the destination

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "7d7ef61a-9def-4de5-96bf-c0193252378d"}' \
  https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/copy

Response: 200 OK -- returns the folder object at its new location.

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

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions
  • 404 Not Found -- folder does not exist
  • 409 Conflict -- name conflict and conflicts is cancel

Trash a Folder

Moves a folder to the user's trash folder. This is a soft delete -- the folder and its contents can be restored by moving them back out of trash. Use the Move Folder endpoint with the trash folder ID.

The conflicts parameter is ignored when moving to trash. You cannot move items to another user's trash folder.

POST /api/v1/canvas-folders/:folder_id/move
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder to trash

Request body (JSON):

  • folder_id (string, required) -- the trash folder ID (format: trash.<user-id>)

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "trash.1000"}' \
  https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/move

Response: 200 OK

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

Permissions

Folder permissions control who can access the folder and its contents. Permissions set on a folder are inherited by child folders and canvases unless explicitly overridden at the child level.

Permission Levels

  • none -- no access
  • view -- read-only access
  • edit -- can create, modify, and delete contents
  • owner -- full control including permission management and deletion

Get Folder Permissions

Returns the permission configuration for a folder, including per-user and per-group overrides.

GET /api/v1/canvas-folders/:folder_id/permissions
  • Authentication: Required
  • Streaming: Supported

Path parameters:

  • folder-id (string, required) -- the folder ID

Query parameters:

  • subscribe (boolean, optional) -- enable streaming

curl example:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/permissions

Response: 200 OK

{
  "editors_can_share": true,
  "users": [
    {
      "id": 1000,
      "inherited": false,
      "permission": "owner"
    },
    {
      "id": 1050,
      "inherited": false,
      "permission": "edit"
    }
  ],
  "groups": [
    {
      "id": 5,
      "inherited": false,
      "permission": "view"
    }
  ]
}

Response fields:

  • editors_can_share (boolean) -- when true, users with edit access can also modify permissions
  • users (array) -- per-user permission overrides
  • id (integer) -- user ID
  • inherited (boolean) -- whether this permission is inherited from a parent folder
  • permission (string) -- permission level
  • groups (array) -- per-group permission overrides
  • id (integer) -- group ID
  • inherited (boolean) -- whether this permission is inherited from a parent folder
  • permission (string) -- permission level

Tip: The access field on the folder object itself provides a quick way to check the requesting user's effective permission without calling this endpoint.

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 404 Not Found -- folder does not exist

Set Folder Permissions

Replaces the permission configuration for a folder.

POST /api/v1/canvas-folders/:folder_id/permissions
  • Authentication: Required
  • Streaming: Not supported

Path parameters:

  • folder-id (string, required) -- the folder ID

Request body (JSON):

  • editors_can_share (boolean, optional) -- whether users with edit access can change permissions
  • users (array, optional) -- per-user permission overrides
  • groups (array, optional) -- per-group permission overrides

Each entry in the users and groups arrays is an object with:

  • id (integer, required) -- the user or group ID
  • permission (string, required) -- one of none, view, edit, or owner

curl example:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "editors_can_share": false,
    "users": [{"id": 1050, "permission": "edit"}],
    "groups": [{"id": 5, "permission": "view"}]
  }' \
  https://canvus.example.com/api/v1/canvas-folders/b574c9f9-2717-4c95-b6dd-c48d146c28f3/permissions

Response: 200 OK

{
  "editors_can_share": false,
  "users": [
    {
      "id": 1000,
      "inherited": false,
      "permission": "owner"
    },
    {
      "id": 1050,
      "inherited": false,
      "permission": "edit"
    }
  ],
  "groups": [
    {
      "id": 5,
      "inherited": false,
      "permission": "view"
    }
  ]
}

Error responses:

  • 401 Unauthorized -- missing or invalid token
  • 403 Forbidden -- insufficient permissions (must be owner or editor with sharing enabled)
  • 404 Not Found -- folder does not exist