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,

  // If self-signup is enabled, group_limit can be set to cap the number of users
  // in each group. If null, there is no limit.
  group_limit: null

  // If the group category has not yet finished a randomly student assignment request,
  // a progress object will be attached, which will contain information related to the
  // progress of the assignment request.
  // Refer to the Progress API for more information
   "progress": {
       "completion": 0,
       "context_id": 25,
       "context_type": "GroupCategory",
       "created_at": "2013-07-25T14:16:04-06:00",
       "id": 217,
       "message": null,
       "tag": "assign_unassigned_members",
       "updated_at": "2013-07-25T14:16:04-06:00",
       "user_id": null,
       "workflow_state": "running",
       "url": "http://localhost:3000/api/v1/progress/217"
   }

}

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 sign up 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

group_limit
Optional
Course Only

Limit the maximum number of users in each group. Requires self signup.
create_group_count
Optional
Course Only

create this number of groups
split_group_count
Optional
Course Only
Deprecated

create this number of groups, and evenly distribute students among them. not allowed with "enable_self_signup". because the group assignment happens synchronously, it's recommended that you instead use the assign_unassigned_members endpoint

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

group_limit
Optional
Course Only

Limit the maximum number of users in each group. Requires self signup.
create_group_count
Optional
Course Only

create this number of groups
split_group_count
Optional
Course Only
Deprecated

create this number of groups, and evenly distribute students among them. not allowed with "enable_self_signup". because the group assignment happens synchronously, it's recommended that you instead use the assign_unassigned_members endpoint

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

List users GroupCategoriesController#users

GET /api/v1/group_categories/:group_category_id/users

Returns a list of users in the group category.

Request Parameters:

search_term

(optional) The partial name or full ID of the users to match and return in the results list. Must be at least 3 characters.
unassigned

(optional) Set this value to true if you wish only to search unassigned users in the group category

Example Request:

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

Returns a list of Users

Assign unassigned members GroupCategoriesController#assign_unassigned_members

POST /api/v1/group_categories/:group_category_id/assign_unassigned_members

Assign all unassigned members as evenly as possible among the existing student groups.

Request Parameters:

sync

(optional) The assigning is done asynchronously by default. If you would like to override this and have the assigning done synchronously, set this value to true.

Example Request:

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

Example Response:

# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "GroupCategory",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "assign_unassigned_members",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}

# New Group Memberships (when sync = true)
[
  {
    "id": 65,
    "new_members": [
      {
        "user_id": 2,
        "name": "Sam",
        "display_name": "Sam",
        "sections": [
          {
            "section_id": 1,
            "section_code": "Section 1"
          }
        ]
      },
      {
        "user_id": 3,
        "name": "Sue",
        "display_name": "Sue",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      }
    ]
  },
  {
    "id": 66,
    "new_members": [
      {
        "user_id": 5,
        "name": "Joe",
        "display_name": "Joe",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      },
      {
        "user_id": 11,
        "name": "Cecil",
        "display_name": "Cecil",
        "sections": [
          {
            "section_id": 3,
            "section_code": "Section 3"
          }
        ]
      }
    ]
  }
]