🚀 Heads up: Our API Docs Have Moved!
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.
Sections API
API for accessing section information.
A Section object looks like:
{
// The unique identifier for the section.
"id": 1,
// The name of the section.
"name": "Section A",
// The sis id of the section. This field is only included if the user has
// permission to view SIS information.
"sis_section_id": "s34643",
// Optional: The integration ID of the section. This field is only included if
// the user has permission to view SIS information.
"integration_id": "3452342345",
// The unique identifier for the SIS import if created through SIS. This field
// is only included if the user has permission to manage SIS information.
"sis_import_id": 47,
// The unique Canvas identifier for the course in which the section belongs
"course_id": 7,
// The unique SIS identifier for the course in which the section belongs. This
// field is only included if the user has permission to view SIS information.
"sis_course_id": "7",
// the start date for the section, if applicable
"start_at": "2012-06-01T00:00:00-06:00",
// the end date for the section, if applicable
"end_at": null,
// Restrict user enrollments to the start and end dates of the section
"restrict_enrollments_to_section_dates": null,
// The unique identifier of the original course of a cross-listed section
"nonxlist_course_id": null,
// optional: the total number of active and invited students in the section
"total_students": 13,
// optional: A list of students that are included in the section. Returned only
// if include[]=students. WARNING: this collection's size is capped (if there
// are an extremely large number of users in the section (thousands) not all of
// them will be returned). If you need to capture all the users in a section
// with certainty or experiencing slow response consider using the paginated
// /api/v1/sections/<section_id>/users endpoint.
"students": null
}
List course sections SectionsController#index
GET /api/v1/courses/:course_id/sections
Scope:
A paginated list of the list of sections for this course.
url:GET|/api/v1/courses/:course_id/sections
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| include[] | string |
- "students": Associations to include with the group. Note: this is only
available if you have permission to view users or grades in the course
- "avatar_url": Include the avatar URLs for students returned.
- "enrollments": If 'students' is also included, return the section
enrollment for each student
- "total_students": Returns the total amount of active and invited students
for the course section
- "passback_status": Include the grade passback status.
- "permissions": Include whether section grants :manage_calendar permission
to the caller
Allowed values: |
|
| search_term | string | When included, searches course sections for the term. Returns only matching results. Term must be at least 2 characters. |
Create course section SectionsController#create
POST /api/v1/courses/:course_id/sections
Scope:
Creates a new section for this course.
url:POST|/api/v1/courses/:course_id/sections
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| course_section[name] | string | The name of the section | |
| course_section[sis_section_id] | string | The sis ID of the section. Must have manage_sis permission to set. This is ignored if caller does not have permission to set. | |
| course_section[integration_id] | string | The integration_id of the section. Must have manage_sis permission to set. This is ignored if caller does not have permission to set. | |
| course_section[start_at] | DateTime | Section start date in ISO8601 format, e.g. 2011-01-01T01:00Z | |
| course_section[end_at] | DateTime | Section end date in ISO8601 format. e.g. 2011-01-01T01:00Z | |
| course_section[restrict_enrollments_to_section_dates] | boolean | Set to true to restrict user enrollments to the start and end dates of the section. | |
| enable_sis_reactivation | boolean | When true, will first try to re-activate a deleted section with matching sis_section_id if possible. |
Cross-list a Section SectionsController#crosslist
POST /api/v1/sections/:id/crosslist/:new_course_id
Scope:
Move the Section to another course. The new course may be in a different account (department),
but must belong to the same root account (institution).
url:POST|/api/v1/sections/:id/crosslist/:new_course_id
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| override_sis_stickiness | boolean | Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness |
De-cross-list a Section SectionsController#uncrosslist
DELETE /api/v1/sections/:id/crosslist
Scope:
Undo cross-listing of a Section, returning it to its original course.
url:DELETE|/api/v1/sections/:id/crosslist
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| override_sis_stickiness | boolean | Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness |
Edit a section SectionsController#update
PUT /api/v1/sections/:id
Scope:
Modify an existing section.
url:PUT|/api/v1/sections/:id
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| course_section[name] | string | The name of the section | |
| course_section[sis_section_id] | string | The sis ID of the section. Must have manage_sis permission to set. | |
| course_section[integration_id] | string | The integration_id of the section. Must have manage_sis permission to set. | |
| course_section[start_at] | DateTime | Section start date in ISO8601 format, e.g. 2011-01-01T01:00Z | |
| course_section[end_at] | DateTime | Section end date in ISO8601 format. e.g. 2011-01-01T01:00Z | |
| course_section[restrict_enrollments_to_section_dates] | boolean | Set to true to restrict user enrollments to the start and end dates of the section. | |
| override_sis_stickiness | boolean | Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness |
Get section information SectionsController#show
GET /api/v1/courses/:course_id/sections/:id
Scope:
url:GET|/api/v1/courses/:course_id/sections/:id
GET /api/v1/sections/:id
Scope:
Gets details about a specific section
url:GET|/api/v1/sections/:id
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| include[] | string |
- "students": Associations to include with the group. Note: this is only
available if you have permission to view users or grades in the course
- "avatar_url": Include the avatar URLs for students returned.
- "enrollments": If 'students' is also included, return the section
enrollment for each student
- "total_students": Returns the total amount of active and invited students
for the course section
- "passback_status": Include the grade passback status.
- "permissions": Include whether section grants :manage_calendar permission
to the caller
Allowed values: |
Delete a section SectionsController#destroy
DELETE /api/v1/sections/:id
Scope:
Delete an existing section. Returns the former Section.
Returns a
Section
object
url:DELETE|/api/v1/sections/:id
List section's users SectionsController#users
GET /api/v1/sections/:id/users
Scope:
Returns a paginated list of users in the section.
url:GET|/api/v1/sections/:id/users
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 2 characters. | |
| include[] | string |
"avatar_url": Include users' avatar_urls.
Allowed values: |
|
| exclude_inactive | boolean | Whether to filter out inactive users from the results. Defaults to false unless explicitly provided. | |
| enrollment_type | string |
When set, only return users with the specified enrollment type for the given section.
Allowed values: |
Example Request:
curl https://<canvas>/api/v1/sections/1/users \
-H 'Authorization: Bearer <token>'