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 GroupCategory 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": "",
  
  //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": ,
  
  //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": ""
}

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>'
Returns a list of GroupCategories

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>'
Returns a GroupCategory

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
    String

    Name of the group category

  • self_signup
    Optional, "enabled"|"restricted"

    Allow students to sign up for a group themselves (Course Only). 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

    Limit the maximum number of users in each group (Course Only). Requires self signup.

  • create_group_count
    Optional

    Create this number of groups (Course Only).

  • split_group_count
    Optional

    (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. (Course Only)

Example Request:

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

Update a Group Category GroupCategoriesController#update

PUT /api/v1/group_categories/:group_category_id

Modifies an existing group category.

Request Parameters:

  • name
    String

    Name of the group category

  • self_signup
    Optional, "enabled"|"restricted"

    Allow students to sign up for a group themselves (Course Only). 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

    Limit the maximum number of users in each group (Course Only). Requires self signup.

  • create_group_count
    Optional

    Create this number of groups (Course Only).

  • split_group_count
    Optional

    (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. (Course Only)

Example Request:

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

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>'
Returns a list of Groups

List users in group category 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, String

    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, Boolean

    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, Boolean

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