# Sections {% hint style="warning" %} **Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)). {% endhint %} ## Sections API API for accessing section information. **A Section object looks like:** ```js { // 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//users endpoint. "students": null } ``` ### [List course sections](#method.sections.index) [SectionsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`GET /api/v1/courses/:course_id/sections`** **Scope:** `url:GET|/api/v1/courses/:course_id/sections` A paginated list of the list of sections for this course. **Request Parameters:** | Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `include[]` | `string` |

Allowed values: students, avatar\_url, enrollments, total\_students, passback\_status, permissions

| | `search_term` | `string` | When included, searches course sections for the term. Returns only matching results. Term must be at least 2 characters. | Returns a list of [Section](#section) objects. ### [Create course section](#method.sections.create) [SectionsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`POST /api/v1/courses/:course_id/sections`** **Scope:** `url:POST|/api/v1/courses/:course_id/sections` Creates a new section for this course. **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. | Returns a [Section](#section) object. ### [Cross-list a Section](#method.sections.crosslist) [SectionsController#crosslist](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`POST /api/v1/sections/:id/crosslist/:new_course_id`** **Scope:** `url:POST|/api/v1/sections/:id/crosslist/:new_course_id` 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). **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 | Returns a [Section](#section) object. ### [De-cross-list a Section](#method.sections.uncrosslist) [SectionsController#uncrosslist](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`DELETE /api/v1/sections/:id/crosslist`** **Scope:** `url:DELETE|/api/v1/sections/:id/crosslist` Undo cross-listing of a Section, returning it to its original course. **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 | Returns a [Section](#section) object. ### [Edit a section](#method.sections.update) [SectionsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`PUT /api/v1/sections/:id`** **Scope:** `url:PUT|/api/v1/sections/:id` Modify an existing section. **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 | Returns a [Section](#section) object. ### [Get section information](#method.sections.show) [SectionsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`GET /api/v1/courses/:course_id/sections/:id`** **Scope:** `url:GET|/api/v1/courses/:course_id/sections/:id` **`GET /api/v1/sections/:id`** **Scope:** `url:GET|/api/v1/sections/:id` Gets details about a specific section **Request Parameters:** | Parameter | Type | Description | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `include[]` | `string` |

Allowed values: students, avatar\_url, enrollments, total\_students, passback\_status, permissions

| Returns a [Section](#section) object. ### [Delete a section](#method.sections.destroy) [SectionsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`DELETE /api/v1/sections/:id`** **Scope:** `url:DELETE|/api/v1/sections/:id` Delete an existing section. Returns the former Section. Returns a [Section](#section) object. ### [List section's users](#method.sections.users) [SectionsController#users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/sections_controller.rb) **`GET /api/v1/sections/:id/users`** **Scope:** `url:GET|/api/v1/sections/:id/users` Returns a paginated list of users in the section. **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: avatar\_url

| | `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: teacher, student, ta, observer, designer

| **Example Request:** ```bash curl https:///api/v1/sections/1/users \ -H 'Authorization: Bearer ' ``` Returns a list of [User](/services/canvas/resources/users.md#user) objects. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developerdocs.instructure.com/services/canvas/resources/sections.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.