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": null,
// Gives instructors the ability to automatically have group leaders assigned.
// Values include 'random', 'first', and null; 'random' picks a student from the
// group at random as the leader, 'first' sets the first student to be assigned
// to the group as the leader
"auto_leader": 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,
// The SIS identifier for the group category. This field is only included if the
// user has permission to manage or view SIS information.
"sis_group_category_id": null,
// The unique identifier for the SIS import. This field is only included if the
// user has permission to manage SIS information.
"sis_import_id": 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": null
}
List group categories for a context GroupCategoriesController#index
GET /api/v1/accounts/:account_id/group_categories
url:GET|/api/v1/accounts/:account_id/group_categories
GET /api/v1/courses/:course_id/group_categories
url:GET|/api/v1/courses/:course_id/group_categories
Returns a paginated 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
url: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
url:POST|/api/v1/accounts/:account_id/group_categories
POST /api/v1/courses/:course_id/group_categories
url:POST|/api/v1/courses/:course_id/group_categories
Create a new group category
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
name | Required | string |
Name of the group category |
self_signup | string |
Allow students to sign up for a group themselves (Course Only). valid values are:
Allowed values: |
|
auto_leader | string |
Assigns group leaders automatically when generating and allocating students to groups Valid values are:
Allowed values: |
|
group_limit | integer |
Limit the maximum number of users in each group (Course Only). Requires self signup. |
|
sis_group_category_id | string |
The unique SIS identifier. |
|
create_group_count | integer |
Create this number of groups (Course Only). |
|
split_group_count | string |
(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>'
Import category groups GroupCategoriesController#import
POST /api/v1/group_categories/:group_category_id/import
url:POST|/api/v1/group_categories/:group_category_id/import
Create Groups in a Group Category through a CSV import
For more information on the format that’s expected here, please see the “Group Category CSV” section in the API docs.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
attachment | string |
There are two ways to post group category import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request. ‘attachment’ is required for multipart/form-data style posts. Assumed to be outcome data from a file upload form field named ‘attachment’. Examples:
If you decide to do a raw post, you can skip the ‘attachment’ argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the ‘extension’ argument. Examples:
|
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": "course_group_import",
"updated_at": "2013-07-05T10:57:48-06:00",
"user_id": null,
"workflow_state": "running",
"url": "http://localhost:3000/api/v1/progress/2"
}
Update a Group Category GroupCategoriesController#update
PUT /api/v1/group_categories/:group_category_id
url:PUT|/api/v1/group_categories/:group_category_id
Modifies an existing group category.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
name | string |
Name of the group category |
|
self_signup | string |
Allow students to sign up for a group themselves (Course Only). Valid values are:
Allowed values: |
|
auto_leader | string |
Assigns group leaders automatically when generating and allocating students to groups Valid values are:
Allowed values: |
|
group_limit | integer |
Limit the maximum number of users in each group (Course Only). Requires self signup. |
|
sis_group_category_id | string |
The unique SIS identifier. |
|
create_group_count | integer |
Create this number of groups (Course Only). |
|
split_group_count | string |
(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>'
Delete a Group Category GroupCategoriesController#destroy
DELETE /api/v1/group_categories/:group_category_id
url: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” and “student_organized”.
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
url:GET|/api/v1/group_categories/:group_category_id/groups
Returns a paginated list of groups in a group category
Example Request:
curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \
-H 'Authorization: Bearer <token>'
export groups in and users in category GroupCategoriesController#export
BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.
GET /api/v1/group_categories/:group_category_id/export
url:GET|/api/v1/group_categories/:group_category_id/export
Returns a csv file of users in format ready to import.
Example Request:
curl https://<canvas>/api/v1/group_categories/<group_category_id>/export \
-H 'Authorization: Bearer <token>'
List users in group category GroupCategoriesController#users
GET /api/v1/group_categories/:group_category_id/users
url:GET|/api/v1/group_categories/:group_category_id/users
Returns a paginated list of users in the group category.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
search_term | 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 | 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>'
Assign unassigned members GroupCategoriesController#assign_unassigned_members
POST /api/v1/group_categories/:group_category_id/assign_unassigned_members
url: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:
Parameter | Type | Description | |
---|---|---|---|
sync | 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"
}
]
}
]
}
]