Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Canvas LMS REST Enrollments API
version: v1
summary: The complete Canvas LMS REST API, converted from the Swagger 1.2 documents Instructure publishes under https://canvas.instructure.com/doc/api/.
description: The Canvas LMS REST API covers courses, assignments, quizzes, grades, users, enrollments, accounts, files, modules, rubrics, submissions, SIS imports, LTI, analytics and account administration.
contact:
name: Instructure Canvas
url: https://canvas.instructure.com/doc/api/
license:
name: AGPL-3.0
url: https://github.com/instructure/canvas-lms/blob/master/LICENSE
servers:
- url: https://canvas.instructure.com/api
description: Instructure-hosted Canvas (canvas.instructure.com)
- url: https://{canvas_host}/api
description: Any Canvas instance; Canvas is multi-tenant and self-hostable, so the host is the institution's Canvas domain.
variables:
canvas_host:
default: canvas.instructure.com
description: Your institution's Canvas hostname, e.g. school.instructure.com
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Enrollments
x-resource: enrollments
externalDocs:
url: https://canvas.instructure.com/doc/api/enrollments.html
paths:
/v1/courses/{course_id}/enrollments:
get:
tags:
- Enrollments
operationId: list_enrollments_courses
summary: List enrollments
description: 'Depending on the URL given, return a paginated list of either (1) all of
the enrollments in a course, (2) all of the enrollments in a section or (3)
all of a user''s enrollments. This includes student, teacher, TA, and
observer enrollments.
If a user has multiple enrollments in a context (e.g. as a teacher
and a student or in multiple course sections), each enrollment will be
listed separately.
note: Currently, only a root level admin user can return other users'' enrollments.
A user can, however, return his/her own enrollments.
Enrollments scoped to a course context will include inactive states by default
if the caller has account admin authorization and the state[] parameter is omitted.'
parameters:
- name: course_id
in: path
schema:
type: string
required: true
description: ID
- name: type
in: query
schema:
type: array
items:
type: string
required: false
description: 'A list of enrollment types to return. Accepted values are
''StudentEnrollment'', ''TeacherEnrollment'', ''TaEnrollment'',
''DesignerEnrollment'', and ''ObserverEnrollment.'' If omitted, all enrollment
types are returned. This argument is ignored if `role` is given.'
- name: role
in: query
schema:
type: array
items:
type: string
required: false
description: 'A list of enrollment roles to return. Accepted values include course-level
roles created by the {api:RoleOverridesController#add_role Add Role API}
as well as the base enrollment types accepted by the `type` argument above.'
- name: state
in: query
schema:
type: array
items:
type: string
enum:
- active
- invited
- creation_pending
- deleted
- rejected
- completed
- inactive
- current_and_invited
- current_and_future
- current_future_and_restricted
- current_and_concluded
required: false
description: 'Filter by enrollment state. If omitted, ''active'' and ''invited'' enrollments
are returned. The following synthetic states are supported only when
querying a user''s enrollments (either via user_id argument or via user
enrollments endpoint): +current_and_invited+, +current_and_future+, +current_future_and_restricted+, +current_and_concluded+'
- name: include
in: query
schema:
type: array
items:
type: string
enum:
- avatar_url
- group_ids
- locked
- observed_users
- can_be_removed
- uuid
- current_points
required: false
description: 'Array of additional information to include on the enrollment or user records.
"avatar_url" and "group_ids" will be returned on the user record. If "current_points"
is specified, the fields "current_points" and (if the caller has
permissions to manage grades) "unposted_current_points" will be included
in the "grades" hash for student enrollments.'
- name: user_id
in: query
schema:
type: string
required: false
description: 'Filter by user_id (only valid for course or section enrollment
queries). If set to the current user''s id, this is a way to
determine if the user has any enrollments in the course or section,
independent of whether the user has permission to view other people
on the roster.'
- name: grading_period_id
in: query
schema:
type: integer
format: int64
required: false
description: 'Return grades for the given grading_period. If this parameter is not
specified, the returned grades will be for the whole course.'
- name: enrollment_term_id
in: query
schema:
type: integer
format: int64
required: false
description: 'Returns only enrollments for the specified enrollment term. This parameter
only applies to the user enrollments path. May pass the ID from the
enrollment terms api or the SIS id prepended with ''sis_term_id:''.'
- name: sis_account_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only enrollments for the specified SIS account ID(s). Does not
look into sub_accounts. May pass in array or string.'
- name: sis_course_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only enrollments matching the specified SIS course ID(s).
May pass in array or string.'
- name: sis_section_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only section enrollments matching the specified SIS section ID(s).
May pass in array or string.'
- name: sis_user_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only enrollments for the specified SIS user ID(s). May pass in
array or string.'
- name: created_for_sis_id
in: query
schema:
type: array
items:
type: boolean
required: false
description: 'If sis_user_id is present and created_for_sis_id is true, Returns only
enrollments for the specified SIS ID(s).
If a user has two sis_id''s, one enrollment may be created using one of the
two ids. This would limit the enrollments returned from the endpoint to
enrollments that were created from a sis_import with that sis_user_id'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Enrollment'
externalDocs:
url: https://canvas.instructure.com/doc/api/enrollments.html
post:
tags:
- Enrollments
operationId: enroll_user_courses
summary: Enroll a user
description: Create a new user enrollment for a course or section.
parameters:
- name: course_id
in: path
schema:
type: string
required: true
description: ID
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
enrollment[start_at]:
type: string
format: date-time
description: The start time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z
enrollment[end_at]:
type: string
format: date-time
description: The end time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z
enrollment[user_id]:
type: string
description: The ID of the user to be enrolled in the course.
enrollment[type]:
type: string
enum:
- StudentEnrollment
- TeacherEnrollment
- TaEnrollment
- ObserverEnrollment
- DesignerEnrollment
description: 'Enroll the user as a student, teacher, TA, observer, or designer. If no
value is given, the type will be inferred by +enrollment[role]+ if supplied,
otherwise ''StudentEnrollment'' will be used.'
enrollment[role]:
type: string
x-canvas-declared-type: Deprecated
description: Assigns a custom course-level role to the user.
enrollment[role_id]:
type: integer
format: int64
description: Assigns a custom course-level role to the user.
enrollment[enrollment_state]:
type: string
enum:
- active
- invited
- inactive
description: 'If set to ''active,'' student will be immediately enrolled in the course.
Otherwise they will be required to accept a course invitation. Default is
''invited.''.
If set to ''inactive'', student will be listed in the course roster for
teachers, but will not be able to participate in the course until
their enrollment is activated.'
enrollment[course_section_id]:
type: integer
format: int64
description: 'The ID of the course section to enroll the student in. If the
section-specific URL is used, this argument is redundant and will be
ignored.'
enrollment[limit_privileges_to_course_section]:
type: boolean
description: "If set, the enrollment will only allow the user to see and interact with\nusers enrolled in the section given by course_section_id.\n* For teachers and TAs, this includes grading privileges.\n* Section-limited students will not see any users (including teachers\n and TAs) not enrolled in their sections.\n* Users may have other enrollments that grant privileges to\n multiple sections in the same course."
enrollment[notify]:
type: boolean
description: 'If true, a notification will be sent to the enrolled user.
Notifications are not sent by default.'
enrollment[self_enrollment_code]:
type: string
description: 'If the current user is not allowed to manage enrollments in this
course, but the course allows self-enrollment, the user can self-
enroll as a student in the default section by passing in a valid
code. When self-enrolling, the user_id must be ''self''. The
enrollment_state will be set to ''active'' and all other arguments
will be ignored.'
enrollment[self_enrolled]:
type: boolean
description: 'If true, marks the enrollment as a self-enrollment, which gives
students the ability to drop the course if desired. Defaults to false.'
enrollment[associated_user_id]:
type: integer
format: int64
description: 'For an observer enrollment, the ID of a student to observe.
This is a one-off operation; to automatically observe all a
student''s enrollments (for example, as a parent), please use
the {api:UserObserveesController#create User Observees API}.'
enrollment[sis_user_id]:
type: string
description: 'Required if the user is being enrolled from another trusted account.
The unique identifier for the user (sis_user_id) must also be
accompanied by the root_account parameter. The user_id will be ignored.'
enrollment[integration_id]:
type: string
description: 'Required if the user is being enrolled from another trusted account.
The unique identifier for the user (integration_id) must also be
accompanied by the root_account parameter. The user_id will be ignored.'
root_account:
type: string
description: 'The domain of the account to search for the user. Will be a no-op
unless the sis_user_id or integration_id parameter is also included.'
required:
- enrollment[user_id]
- enrollment[type]
application/x-www-form-urlencoded:
schema:
type: object
properties:
enrollment[start_at]:
type: string
format: date-time
description: The start time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z
enrollment[end_at]:
type: string
format: date-time
description: The end time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z
enrollment[user_id]:
type: string
description: The ID of the user to be enrolled in the course.
enrollment[type]:
type: string
enum:
- StudentEnrollment
- TeacherEnrollment
- TaEnrollment
- ObserverEnrollment
- DesignerEnrollment
description: 'Enroll the user as a student, teacher, TA, observer, or designer. If no
value is given, the type will be inferred by +enrollment[role]+ if supplied,
otherwise ''StudentEnrollment'' will be used.'
enrollment[role]:
type: string
x-canvas-declared-type: Deprecated
description: Assigns a custom course-level role to the user.
enrollment[role_id]:
type: integer
format: int64
description: Assigns a custom course-level role to the user.
enrollment[enrollment_state]:
type: string
enum:
- active
- invited
- inactive
description: 'If set to ''active,'' student will be immediately enrolled in the course.
Otherwise they will be required to accept a course invitation. Default is
''invited.''.
If set to ''inactive'', student will be listed in the course roster for
teachers, but will not be able to participate in the course until
their enrollment is activated.'
enrollment[course_section_id]:
type: integer
format: int64
description: 'The ID of the course section to enroll the student in. If the
section-specific URL is used, this argument is redundant and will be
ignored.'
enrollment[limit_privileges_to_course_section]:
type: boolean
description: "If set, the enrollment will only allow the user to see and interact with\nusers enrolled in the section given by course_section_id.\n* For teachers and TAs, this includes grading privileges.\n* Section-limited students will not see any users (including teachers\n and TAs) not enrolled in their sections.\n* Users may have other enrollments that grant privileges to\n multiple sections in the same course."
enrollment[notify]:
type: boolean
description: 'If true, a notification will be sent to the enrolled user.
Notifications are not sent by default.'
enrollment[self_enrollment_code]:
type: string
description: 'If the current user is not allowed to manage enrollments in this
course, but the course allows self-enrollment, the user can self-
enroll as a student in the default section by passing in a valid
code. When self-enrolling, the user_id must be ''self''. The
enrollment_state will be set to ''active'' and all other arguments
will be ignored.'
enrollment[self_enrolled]:
type: boolean
description: 'If true, marks the enrollment as a self-enrollment, which gives
students the ability to drop the course if desired. Defaults to false.'
enrollment[associated_user_id]:
type: integer
format: int64
description: 'For an observer enrollment, the ID of a student to observe.
This is a one-off operation; to automatically observe all a
student''s enrollments (for example, as a parent), please use
the {api:UserObserveesController#create User Observees API}.'
enrollment[sis_user_id]:
type: string
description: 'Required if the user is being enrolled from another trusted account.
The unique identifier for the user (sis_user_id) must also be
accompanied by the root_account parameter. The user_id will be ignored.'
enrollment[integration_id]:
type: string
description: 'Required if the user is being enrolled from another trusted account.
The unique identifier for the user (integration_id) must also be
accompanied by the root_account parameter. The user_id will be ignored.'
root_account:
type: string
description: 'The domain of the account to search for the user. Will be a no-op
unless the sis_user_id or integration_id parameter is also included.'
required:
- enrollment[user_id]
- enrollment[type]
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Enrollment'
externalDocs:
url: https://canvas.instructure.com/doc/api/enrollments.html
/v1/sections/{section_id}/enrollments:
get:
tags:
- Enrollments
operationId: list_enrollments_sections
summary: List enrollments
description: 'Depending on the URL given, return a paginated list of either (1) all of
the enrollments in a course, (2) all of the enrollments in a section or (3)
all of a user''s enrollments. This includes student, teacher, TA, and
observer enrollments.
If a user has multiple enrollments in a context (e.g. as a teacher
and a student or in multiple course sections), each enrollment will be
listed separately.
note: Currently, only a root level admin user can return other users'' enrollments.
A user can, however, return his/her own enrollments.
Enrollments scoped to a course context will include inactive states by default
if the caller has account admin authorization and the state[] parameter is omitted.'
parameters:
- name: section_id
in: path
schema:
type: string
required: true
description: ID
- name: type
in: query
schema:
type: array
items:
type: string
required: false
description: 'A list of enrollment types to return. Accepted values are
''StudentEnrollment'', ''TeacherEnrollment'', ''TaEnrollment'',
''DesignerEnrollment'', and ''ObserverEnrollment.'' If omitted, all enrollment
types are returned. This argument is ignored if `role` is given.'
- name: role
in: query
schema:
type: array
items:
type: string
required: false
description: 'A list of enrollment roles to return. Accepted values include course-level
roles created by the {api:RoleOverridesController#add_role Add Role API}
as well as the base enrollment types accepted by the `type` argument above.'
- name: state
in: query
schema:
type: array
items:
type: string
enum:
- active
- invited
- creation_pending
- deleted
- rejected
- completed
- inactive
- current_and_invited
- current_and_future
- current_future_and_restricted
- current_and_concluded
required: false
description: 'Filter by enrollment state. If omitted, ''active'' and ''invited'' enrollments
are returned. The following synthetic states are supported only when
querying a user''s enrollments (either via user_id argument or via user
enrollments endpoint): +current_and_invited+, +current_and_future+, +current_future_and_restricted+, +current_and_concluded+'
- name: include
in: query
schema:
type: array
items:
type: string
enum:
- avatar_url
- group_ids
- locked
- observed_users
- can_be_removed
- uuid
- current_points
required: false
description: 'Array of additional information to include on the enrollment or user records.
"avatar_url" and "group_ids" will be returned on the user record. If "current_points"
is specified, the fields "current_points" and (if the caller has
permissions to manage grades) "unposted_current_points" will be included
in the "grades" hash for student enrollments.'
- name: user_id
in: query
schema:
type: string
required: false
description: 'Filter by user_id (only valid for course or section enrollment
queries). If set to the current user''s id, this is a way to
determine if the user has any enrollments in the course or section,
independent of whether the user has permission to view other people
on the roster.'
- name: grading_period_id
in: query
schema:
type: integer
format: int64
required: false
description: 'Return grades for the given grading_period. If this parameter is not
specified, the returned grades will be for the whole course.'
- name: enrollment_term_id
in: query
schema:
type: integer
format: int64
required: false
description: 'Returns only enrollments for the specified enrollment term. This parameter
only applies to the user enrollments path. May pass the ID from the
enrollment terms api or the SIS id prepended with ''sis_term_id:''.'
- name: sis_account_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only enrollments for the specified SIS account ID(s). Does not
look into sub_accounts. May pass in array or string.'
- name: sis_course_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only enrollments matching the specified SIS course ID(s).
May pass in array or string.'
- name: sis_section_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only section enrollments matching the specified SIS section ID(s).
May pass in array or string.'
- name: sis_user_id
in: query
schema:
type: array
items:
type: string
required: false
description: 'Returns only enrollments for the specified SIS user ID(s). May pass in
array or string.'
- name: created_for_sis_id
in: query
schema:
type: array
items:
type: boolean
required: false
description: 'If sis_user_id is present and created_for_sis_id is true, Returns only
enrollments for the specified SIS ID(s).
If a user has two sis_id''s, one enrollment may be created using one of the
two ids. This would limit the enrollments returned from the endpoint to
enrollments that were created from a sis_import with that sis_user_id'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Enrollment'
externalDocs:
url: https://canvas.instructure.com/doc/api/enrollments.html
post:
tags:
- Enrollments
operationId: enroll_user_sections
summary: Enroll a user
description: Create a new user enrollment for a course or section.
parameters:
- name: section_id
in: path
schema:
type: string
required: true
description: ID
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
enrollment[start_at]:
type: string
format: date-time
description: The start time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z
enrollment[end_at]:
type: string
format: date-time
description: The end time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z
enrollment[user_id]:
type: string
description: The ID of the user to be enrolled in the course.
enrollment[type]:
type: string
enum:
- StudentEnrollment
- TeacherEnrollment
- TaEnrollment
- ObserverEnrollment
- DesignerEnrollment
description: 'Enroll the user as a student, teacher, TA, observer, or designer. If no
value is given, the type will be inferred by +enrollment[role]+ if supplied,
otherwise ''StudentEnrollment'' will be used.'
enrollment[role]:
type: string
x-canvas-declared-type: Deprecated
description: Assigns a custom course-level role to the user.
enrollment[role_id]:
type: integer
format: int64
description: Assigns a custom course-level role to the user.
enrollment[enrollment_state]:
type: string
enum:
- active
- invited
- inactive
description: 'If set to ''active,'' student will be immediately enrolled in the course.
Otherwise they will be required to accept a course invitation. Default is
''invited.''.
If set to ''inactive'', student will be listed in the course roster for
teachers, but will not be able to participate in the course until
their enrollment is activated.'
enrollment[course_section_id]:
type: integer
format: int64
description: 'The ID of the course section to enroll the student in. If the
section-specific URL is used, this argument is redundant and will be
ignored.'
enrollment[limit_privileges_to_course_section]:
type: boolean
description: "If set, the enrollment will only allow the user to see and interact with\nusers enrolled in the section given by course_section_id.\n* For teachers and TAs, this includes grading privileges.\n* Section-limited students will not see any users (including teachers\n and TAs) not enrolled in their sections.\n* Users may have other enrollments that grant privileges to\n multiple sections in the same course."
enrollment[notify]:
type: boolean
description: 'If true, a notification will be sent to the enrolled user.
Notifications are not sent by default.'
enrollment[self_enrollment_code]:
type: string
description: 'If the current user is not allowed to manage enrollments in this
course, but the course allows self-enrollment, the user can self-
enroll as a student in the default section by passing in a valid
code. When self-enrolling, the user_id must be ''self''. The
enrollment_state will be set to ''active'' and all other arguments
will be ignored.'
enrollment[self_enrolled]:
type: boolean
description: 'If true, marks the enrollment as a self-enrollment, which gives
students the ability to drop the course if desired. Defaults to false.'
enrollment[associated_user_id]:
type: integer
format: int64
description: 'For an observer enrollment, the ID of a student to observe.
This is a one-off operation; to automatically observe all a
student''s enrollments (for example, as a parent), please use
the {api:UserObserveesController#create User Observees API}.'
enrollment[sis_user_id]:
type: string
description: 'Required if the user is being enrolled from another trusted account.
The unique identifier for the user (sis_user_id) must also be
accompanied by the root_account parameter. The user_id will be ignored.'
enrollment[integration_id]:
type: string
description: 'Required if the user is being enrolled from another trusted account.
The unique identifier for the user (integration_id) must also be
accompanied by the root_account parameter. The user_id will be ignored.'
root_account:
type: string
description: 'The domain of the account to search for the user. Will be a no-op
unless the sis_user_id or integration_id parameter is also i
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/canvas/refs/heads/main/openapi/canvas-enrollments-api-openapi.yml