Group Categories API

Group Categories allow grouping of groups together in canvas. There are a few different built-in group categories used, or custom ones can be created. The built in group categories are: "communities", "student_organized", and "imported".

A Group Category object looks like:

{
  // The ID of the group category.
  id: 17,

  // The display name of the group category.
  name: "Math Groups",

  // Certain types of group categories have special role designations. Currently,
  // these include: "communities", "student_organized", and "imported".
  // Regular course/account group categories have a role of null.
  role: "communities",

  // If the group category allows users to join a group themselves, thought they may
  // only be a member of one group per group category at a time.
  // Values include "restricted", "enabled", and null
  // "enabled" allows students to assign themselves to a group
  // "restricted" restricts them to only joining a group in their section
  // null disallows students from joining groups
  self_signup: null,

  // The course or account that the category group belongs to. The pattern here is
  // that whatever the context_type is, there will be an _id field named
  // after that type. So if instead context_type was "Course", the
  // course_id field would be replaced by an course_id field.
  context_type: "Account",
  account_id: 3,

}

List group categories for a context GroupCategoriesController#index

GET /api/v1/accounts/:account_id/group_categories

GET /api/v1/courses/:course_id/group_categories

Returns a list of group categories in a context

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/group_categories \ 
     -H 'Authorization: Bearer <token>'

Get a single group category GroupCategoriesController#show

GET /api/v1/group_categories/:group_category_id

Returns the data for a single group category, or a 401 if the caller doesn't have the rights to see it.

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
     -H 'Authorization: Bearer <token>'

Create a Group Category GroupCategoriesController#create

POST /api/v1/accounts/:account_id/group_categories

POST /api/v1/courses/:course_id/group_categories

Create a new group category

Request Parameters:

  • name
  • self_signup
    Optional
    Course Only

    allow students to signup for a group themselves

    valid values are:

    "enabled" allows students to self sign up for any group in course
"restricted" allows students to self sign up only for groups in the same section
null disallows self sign up
  • create_group_count
    Optional
    Course Only

    automatically create groups, requires "enable_self_signup"

  • split_group_count
    Optional
    Course Only

    split students into groups, not allowed with "enable_self_signup"

Example Request:

curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \ 
    -F 'name=Project Groups' \ 
    -H 'Authorization: Bearer <token>'

Update a Group Category GroupCategoriesController#update

PUT /api/v1/group_categories/:group_category_id

Modifies an existing group category.

Request Parameters:

  • name
  • self_signup
    Optional
    Course Only

    allow students to signup for a group themselves

    valid values are:

    "enabled" allows students to self sign up for any group in course
"restricted" allows students to self sign up only for groups in the same section
null disallows self sign up
  • create_group_count
    Optional
    Course Only

    automatically create groups, requires "enable_self_signup"

  • split_group_count
    Optional
    Course Only

    creates groups and split students into groups, not allowed with "enable_self_signup"

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
    -X PUT \ 
    -F 'name=Project Groups' \ 
    -H 'Authorization: Bearer <token>'

Delete a Group Category GroupCategoriesController#destroy

DELETE /api/v1/group_categories/:group_category_id

Deletes a group category and all groups under it. Protected group categories can not be deleted, i.e. "communities", "student_organized", and "imported".

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
      -X DELETE \ 
      -H 'Authorization: Bearer <token>'

List groups in group category GroupCategoriesController#groups

GET /api/v1/group_categories/:group_category_id/groups

Returns a list of groups in a group category

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \ 
     -H 'Authorization: Bearer <token>'