Skip to content

Groups API

Groups organize users into named collections for access control. Canvas and folder permissions can be assigned to groups, so that all members of a group share the same access level.

Every Canvus server has a built-in "All Users" group that automatically contains every user account. Custom groups are created and managed through this API.

Authentication: All endpoints require authentication. Regular users have read-only access (list groups, view members). Write operations (create, delete, add/remove members) require administrator privileges.

Related APIs:

  • User accounts are managed through the Users API
  • Canvas permissions reference groups by ID

Group object

Fields:

  • id (integer) -- unique group identifier
  • name (string) -- display name of the group (unique across all groups)
  • description (string) -- optional description of the group's purpose

Example:

{
  "id": 1000,
  "name": "Engineering",
  "description": "Product engineering team"
}

List Groups

Returns all groups on the server.

GET /api/v1/groups

Authentication: Required.

Streaming: Supports ?subscribe for live updates.

Query parameters:

  • subscribe (boolean, optional) -- if true, keeps the connection open and streams updates as newline-delimited JSON
curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/groups

Response (200 OK):

[
  {
    "id": 1,
    "name": "All Users",
    "description": "All users on this server."
  },
  {
    "id": 1000,
    "name": "Engineering",
    "description": "Product engineering team"
  },
  {
    "id": 1001,
    "name": "Design",
    "description": "UX and visual design"
  }
]

Get Single Group

Returns details for a specific group.

GET /api/v1/groups/:group-id

Authentication: Required.

Streaming: Supports ?subscribe for live updates.

Path parameters:

  • group-id (integer, required) -- the ID of the group
curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/groups/1000

Response (200 OK):

{
  "id": 1000,
  "name": "Engineering",
  "description": "Product engineering team"
}

Error responses:

  • 404 Not Found -- no group with the given ID exists

Create Group

Creates a new group.

POST /api/v1/groups

Authentication: Admin required.

Streaming: Not supported.

Request body (JSON):

  • name (string, required) -- name of the group. Must be unique across all groups.
  • description (string, optional) -- description of the group
curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Marketing","description":"Marketing and communications team"}' \
  https://canvus.example.com/api/v1/groups

Response (201 Created):

{
  "id": 1002,
  "name": "Marketing",
  "description": "Marketing and communications team"
}

Error responses:

  • 400 Bad Request -- missing required name field
  • 403 Forbidden -- caller is not an administrator
  • 409 Conflict -- a group with this name already exists

Update Group

Updates group properties.

PATCH /api/v1/groups/:group-id

Authentication: Admin required.

Streaming: Not supported.

Path parameters:

  • group-id (integer, required) -- the ID of the group to update

Request body (JSON) -- include only fields being changed:

  • name (string, optional) -- new group name. Must be unique.
  • description (string, optional) -- new description
curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Product engineering and QA"}' \
  https://canvus.example.com/api/v1/groups/1000

Response (200 OK):

{
  "id": 1000,
  "name": "Engineering",
  "description": "Product engineering and QA"
}

Error responses:

  • 403 Forbidden -- caller is not an administrator
  • 404 Not Found -- no group with the given ID exists
  • 409 Conflict -- another group already has the requested name

Delete Group

Permanently deletes a group. Members are not deleted -- they simply lose membership in this group.

DELETE /api/v1/groups/:group-id

Authentication: Admin required.

Streaming: Not supported.

Path parameters:

  • group-id (integer, required) -- the ID of the group to delete
curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/groups/1002

Response (200 OK): Empty body on success.

Error responses:

  • 403 Forbidden -- caller is not an administrator
  • 404 Not Found -- no group with the given ID exists

List Group Members

Returns all users that belong to a group. Each entry is a full user object.

GET /api/v1/groups/:group-id/members

Authentication: Required.

Streaming: Supports ?subscribe for live updates.

Path parameters:

  • group-id (integer, required) -- the ID of the group

Query parameters:

  • subscribe (boolean, optional) -- if true, keeps the connection open and streams updates as newline-delimited JSON
curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/groups/1000/members

Response (200 OK):

[
  {
    "id": 1002,
    "name": "Alice Chen",
    "email": "alice@example.com",
    "admin": false,
    "approved": true,
    "blocked": false,
    "state": "normal",
    "created_at": "2025-03-15T09:22:41.817Z",
    "last_login": "2025-03-28T14:05:12.003Z"
  },
  {
    "id": 1003,
    "name": "Bob Martinez",
    "email": "bob.martinez@example.com",
    "admin": false,
    "approved": true,
    "blocked": false,
    "state": "normal",
    "created_at": "2025-03-16T11:30:05.102Z",
    "last_login": "2025-03-27T09:15:44.221Z"
  }
]

Error responses:

  • 404 Not Found -- no group with the given ID exists

Add Member to Group

Adds a user to a group.

POST /api/v1/groups/:group-id/members

Authentication: Admin required.

Streaming: Not supported.

Path parameters:

  • group-id (integer, required) -- the ID of the group

Request body (JSON):

  • id (integer, required) -- the ID of the user to add
curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1002}' \
  https://canvus.example.com/api/v1/groups/1000/members

Response (200 OK): Empty body on success.

Error responses:

  • 400 Bad Request -- missing or invalid user ID
  • 403 Forbidden -- caller is not an administrator
  • 404 Not Found -- group or user does not exist
  • 409 Conflict -- user is already a member of the group

Remove Member from Group

Removes a user from a group.

DELETE /api/v1/groups/:group-id/members/:user-id

Authentication: Admin required.

Streaming: Not supported.

Path parameters:

  • group-id (integer, required) -- the ID of the group
  • user-id (integer, required) -- the ID of the user to remove
curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/groups/1000/members/1002

Response (200 OK): Empty body on success.

Error responses:

  • 403 Forbidden -- caller is not an administrator
  • 404 Not Found -- group or user does not exist, or user is not a member of the group