Courses API

API for accessing course information.

A Term object looks like:

{
  "id": 1,
  "name": "Default Term",
  "start_at": "2012-06-01T00:00:00-06:00",
  "end_at": null
}

A CourseProgress object looks like:

{
  // total number of requirements from all modules
  "requirement_count": 10,
  // total number of requirements the user has completed from all modules
  "requirement_completed_count": 1,
  // url to next module item that has an unmet requirement. null if the user has
  // completed the course or the current module does not require sequential
  // progress
  "next_requirement_url": "http://localhost/courses/1/modules/items/2",
  // date the course was completed. null if the course has not been completed by
  // this user
  "completed_at": "2013-06-01T00:00:00-06:00"
}

A Course object looks like:

{
  // the unique identifier for the course
  "id": 370663,
  // the SIS identifier for the course, if defined. This field is only included if
  // the user has permission to view SIS information.
  "sis_course_id": null,
  // the UUID of the course
  "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5",
  // the integration identifier for the course, if defined. This field is only
  // included if the user has permission to view SIS information.
  "integration_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": 34,
  // the full name of the course
  "name": "InstructureCon 2012",
  // the course code
  "course_code": "INSTCON12",
  // the current state of the course one of 'unpublished', 'available',
  // 'completed', or 'deleted'
  "workflow_state": "available",
  // the account associated with the course
  "account_id": 81259,
  // the root account associated with the course
  "root_account_id": 81259,
  // the enrollment term associated with the course
  "enrollment_term_id": 34,
  // the grading standard associated with the course
  "grading_standard_id": 25,
  // the grade_passback_setting set on the course
  "grade_passback_setting": "nightly_sync",
  // the date the course was created.
  "created_at": "2012-05-01T00:00:00-06:00",
  // the start date for the course, if applicable
  "start_at": "2012-06-01T00:00:00-06:00",
  // the end date for the course, if applicable
  "end_at": "2012-09-01T00:00:00-06:00",
  // the course-set locale, if applicable
  "locale": "en",
  // A list of enrollments linking the current user to the course. for student
  // enrollments, grading information may be included if include[]=total_scores
  "enrollments": null,
  // optional: the total number of active and invited students in the course
  "total_students": 32,
  // course calendar
  "calendar": null,
  // the type of page that users will see when they first visit the course -
  // 'feed': Recent Activity Dashboard - 'wiki': Wiki Front Page - 'modules':
  // Course Modules/Sections Page - 'assignments': Course Assignments List -
  // 'syllabus': Course Syllabus Page other types may be added in the future
  "default_view": "feed",
  // optional: user-generated HTML for the course syllabus
  "syllabus_body": "<p>syllabus html goes here</p>",
  // optional: the number of submissions needing grading returned only if the
  // current user has grading rights and include[]=needs_grading_count
  "needs_grading_count": 17,
  // optional: the enrollment term object for the course returned only if
  // include[]=term
  "term": null,
  // optional: information on progress through the course returned only if
  // include[]=course_progress
  "course_progress": null,
  // weight final grade based on assignment group percentages
  "apply_assignment_group_weights": true,
  // optional: the permissions the user has for the course. returned only for a
  // single course and include[]=permissions
  "permissions": {"create_discussion_topic":true,"create_announcement":true},
  "is_public": true,
  "is_public_to_auth_users": true,
  "public_syllabus": true,
  "public_syllabus_to_auth": true,
  // optional: the public description of the course
  "public_description": "Come one, come all to InstructureCon 2012!",
  "storage_quota_mb": 5,
  "storage_quota_used_mb": 5,
  "hide_final_grades": false,
  "license": "Creative Commons",
  "allow_student_assignment_edits": false,
  "allow_wiki_comments": false,
  "allow_student_forum_attachments": false,
  "open_enrollment": true,
  "self_enrollment": false,
  "restrict_enrollments_to_course_dates": false,
  "course_format": "online",
  // optional: this will be true if this user is currently prevented from viewing
  // the course because of date restriction settings
  "access_restricted_by_date": false,
  // The course's IANA time zone name.
  "time_zone": "America/Denver",
  // optional: whether the course is set as a Blueprint Course (blueprint fields
  // require the Blueprint Courses feature)
  "blueprint": true,
  // optional: Set of restrictions applied to all locked course objects
  "blueprint_restrictions": {"content":true,"points":true,"due_dates":false,"availability_dates":false},
  // optional: Sets of restrictions differentiated by object type applied to
  // locked course objects
  "blueprint_restrictions_by_object_type": {"assignment":{"content":true,"points":true},"wiki_page":{"content":true}}
}

A CalendarLink object looks like:

{
  // The URL of the calendar in ICS format
  "ics": "https://canvas.instructure.com/feeds/calendars/course_abcdef.ics"
}

List your courses CoursesController#index

GET /api/v1/courses

Scope: url:GET|/api/v1/courses

Returns the paginated list of active courses for the current user.

Request Parameters:

Parameter Type Description
enrollment_type string

When set, only return courses where the user is enrolled as this type. For example, set to “teacher” to return only courses where the user is enrolled as a Teacher. This argument is ignored if enrollment_role is given.

Allowed values: teacher, student, ta, observer, designer

enrollment_role string

Deprecated When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the Add Role API or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.

enrollment_role_id integer

When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the Add Role API or a built_in role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.

enrollment_state string

When set, only return courses where the user has an enrollment with the given state. This will respect section/course/term date overrides.

Allowed values: active, invited_or_pending, completed

exclude_blueprint_courses boolean

When set, only return courses that are not configured as blueprint courses.

include[] string
  • “needs_grading_count”: Optional information to include with each Course. When needs_grading_count is given, and the current user has grading rights, the total number of submissions needing grading for all assignments is returned.

  • “syllabus_body”: Optional information to include with each Course. When syllabus_body is given the user-generated html for the course syllabus is returned.

  • “public_description”: Optional information to include with each Course. When public_description is given the user-generated text for the course public description is returned.

  • “total_scores”: Optional information to include with each Course. When total_scores is given, any student enrollments will also include the fields 'computed_current_score', 'computed_final_score', 'computed_current_grade', and 'computed_final_grade', as well as (if the user has permission) 'unposted_current_score', 'unposted_final_score', 'unposted_current_grade', and 'unposted_final_grade' (see Enrollment documentation for more information on these fields). This argument is ignored if the course is configured to hide final grades.

  • “current_grading_period_scores”: Optional information to include with each Course. When current_grading_period_scores is given and total_scores is given, any student enrollments will also include the fields 'has_grading_periods', 'totals_for_all_grading_periods_option', 'current_grading_period_title', 'current_grading_period_id', current_period_computed_current_score', 'current_period_computed_final_score', 'current_period_computed_current_grade', and 'current_period_computed_final_grade', as well as (if the user has permission) 'current_period_unposted_current_score', 'current_period_unposted_final_score', 'current_period_unposted_current_grade', and 'current_period_unposted_final_grade' (see Enrollment documentation for more information on these fields). In addition, when this argument is passed, the course will have a 'has_grading_periods' attribute on it. This argument is ignored if the total_scores argument is not included. If the course is configured to hide final grades, the following fields are not returned: 'totals_for_all_grading_periods_option', 'current_period_computed_current_score', 'current_period_computed_final_score', 'current_period_computed_current_grade', 'current_period_computed_final_grade', 'current_period_unposted_current_score', 'current_period_unposted_final_score', 'current_period_unposted_current_grade', and 'current_period_unposted_final_grade'

  • “term”: Optional information to include with each Course. When term is given, the information for the enrollment term for each course is returned.

  • “account”: Optional information to include with each Course. When account is given, the account json for each course is returned.

  • “course_progress”: Optional information to include with each Course. When course_progress is given, each course will include a 'course_progress' object with the fields: 'requirement_count', an integer specifying the total number of requirements in the course, 'requirement_completed_count', an integer specifying the total number of requirements in this course that have been completed, and 'next_requirement_url', a string url to the next requirement item, and 'completed_at', the date the course was completed (null if incomplete). 'next_requirement_url' will be null if all requirements have been completed or the current module does not require sequential progress. “course_progress” will return an error message if the course is not module based or the user is not enrolled as a student in the course.

  • “sections”: Section enrollment information to include with each Course. Returns an array of hashes containing the section ID (id), section name (name), start and end dates (start_at, end_at), as well as the enrollment type (enrollment_role, e.g. 'StudentEnrollment').

  • “storage_quota_used_mb”: The amount of storage space used by the files in this course

  • “total_students”: Optional information to include with each Course. Returns an integer for the total amount of active and invited students.

  • “passback_status”: Include the grade passback_status

  • “favorites”: Optional information to include with each Course. Indicates if the user has marked the course as a favorite course.

  • “teachers”: Teacher information to include with each Course. Returns an array of hashes containing the UserDisplay information for each teacher in the course.

  • “observed_users”: Optional information to include with each Course. Will include data for observed users if the current user has an observer enrollment.

  • “tabs”: Optional information to include with each Course. Will include the list of tabs configured for each course. See the List available tabs API for more information.

  • “course_image”: Optional course image data for when there is a course image and the course image feature flag has been enabled

  • “concluded”: Optional information to include with each Course. Indicates whether the course has been concluded, taking course and term dates into account.

Allowed values: needs_grading_count, syllabus_body, public_description, total_scores, current_grading_period_scores, term, account, course_progress, sections, storage_quota_used_mb, total_students, passback_status, favorites, teachers, observed_users, course_image, concluded

state[] string

If set, only return courses that are in the given state(s). By default, “available” is returned for students and observers, and anything except “deleted”, for all other enrollment types

Allowed values: unpublished, available, completed, deleted

Returns a list of Courses

List courses for a user CoursesController#user_index

GET /api/v1/users/:user_id/courses

Scope: url:GET|/api/v1/users/:user_id/courses

Returns a paginated list of active courses for this user. To view the course list for a user other than yourself, you must be either an observer of that user or an administrator.

Request Parameters:

Parameter Type Description
include[] string
  • “needs_grading_count”: Optional information to include with each Course. When needs_grading_count is given, and the current user has grading rights, the total number of submissions needing grading for all assignments is returned.

  • “syllabus_body”: Optional information to include with each Course. When syllabus_body is given the user-generated html for the course syllabus is returned.

  • “public_description”: Optional information to include with each Course. When public_description is given the user-generated text for the course public description is returned.

  • “total_scores”: Optional information to include with each Course. When total_scores is given, any student enrollments will also include the fields 'computed_current_score', 'computed_final_score', 'computed_current_grade', and 'computed_final_grade' (see Enrollment documentation for more information on these fields). This argument is ignored if the course is configured to hide final grades.

  • “current_grading_period_scores”: Optional information to include with each Course. When current_grading_period_scores is given and total_scores is given, any student enrollments will also include the fields 'has_grading_periods', 'totals_for_all_grading_periods_option', 'current_grading_period_title', 'current_grading_period_id', current_period_computed_current_score', 'current_period_computed_final_score', 'current_period_computed_current_grade', and 'current_period_computed_final_grade', as well as (if the user has permission) 'current_period_unposted_current_score', 'current_period_unposted_final_score', 'current_period_unposted_current_grade', and 'current_period_unposted_final_grade' (see Enrollment documentation for more information on these fields). In addition, when this argument is passed, the course will have a 'has_grading_periods' attribute on it. This argument is ignored if the course is configured to hide final grades or if the total_scores argument is not included.

  • “term”: Optional information to include with each Course. When term is given, the information for the enrollment term for each course is returned.

  • “account”: Optional information to include with each Course. When account is given, the account json for each course is returned.

  • “course_progress”: Optional information to include with each Course. When course_progress is given, each course will include a 'course_progress' object with the fields: 'requirement_count', an integer specifying the total number of requirements in the course, 'requirement_completed_count', an integer specifying the total number of requirements in this course that have been completed, and 'next_requirement_url', a string url to the next requirement item, and 'completed_at', the date the course was completed (null if incomplete). 'next_requirement_url' will be null if all requirements have been completed or the current module does not require sequential progress. “course_progress” will return an error message if the course is not module based or the user is not enrolled as a student in the course.

  • “sections”: Section enrollment information to include with each Course. Returns an array of hashes containing the section ID (id), section name (name), start and end dates (start_at, end_at), as well as the enrollment type (enrollment_role, e.g. 'StudentEnrollment').

  • “storage_quota_used_mb”: The amount of storage space used by the files in this course

  • “total_students”: Optional information to include with each Course. Returns an integer for the total amount of active and invited students.

  • “passback_status”: Include the grade passback_status

  • “favorites”: Optional information to include with each Course. Indicates if the user has marked the course as a favorite course.

  • “teachers”: Teacher information to include with each Course. Returns an array of hashes containing the UserDisplay information for each teacher in the course.

  • “observed_users”: Optional information to include with each Course. Will include data for observed users if the current user has an observer enrollment.

  • “tabs”: Optional information to include with each Course. Will include the list of tabs configured for each course. See the List available tabs API for more information.

  • “course_image”: Optional course image data for when there is a course image and the course image feature flag has been enabled

  • “concluded”: Optional information to include with each Course. Indicates whether the course has been concluded, taking course and term dates into account.

Allowed values: needs_grading_count, syllabus_body, public_description, total_scores, current_grading_period_scores, term, account, course_progress, sections, storage_quota_used_mb, total_students, passback_status, favorites, teachers, observed_users, course_image, concluded

state[] string

If set, only return courses that are in the given state(s). By default, “available” is returned for students and observers, and anything except “deleted”, for all other enrollment types

Allowed values: unpublished, available, completed, deleted

enrollment_state string

When set, only return courses where the user has an enrollment with the given state. This will respect section/course/term date overrides.

Allowed values: active, invited_or_pending, completed

Returns a list of Courses

Create a new course CoursesController#create

POST /api/v1/accounts/:account_id/courses

Scope: url:POST|/api/v1/accounts/:account_id/courses

Create a new course

Request Parameters:

Parameter Type Description
course[name] string

The name of the course. If omitted, the course will be named “Unnamed Course.”

course[course_code] string

The course code for the course.

course[start_at] DateTime

Course start date in ISO8601 format, e.g. 2011-01-01T01:00Z

course[end_at] DateTime

Course end date in ISO8601 format. e.g. 2011-01-01T01:00Z

course[license] string

The name of the licensing. Should be one of the following abbreviations (a descriptive name is included in parenthesis for reference):

  • 'private' (Private Copyrighted)

  • 'cc_by_nc_nd' (CC Attribution Non-Commercial No Derivatives)

  • 'cc_by_nc_sa' (CC Attribution Non-Commercial Share Alike)

  • 'cc_by_nc' (CC Attribution Non-Commercial)

  • 'cc_by_nd' (CC Attribution No Derivatives)

  • 'cc_by_sa' (CC Attribution Share Alike)

  • 'cc_by' (CC Attribution)

  • 'public_domain' (Public Domain).

course[is_public] boolean

Set to true if course is public to both authenticated and unauthenticated users.

course[is_public_to_auth_users] boolean

Set to true if course is public only to authenticated users.

course[public_syllabus] boolean

Set to true to make the course syllabus public.

course[public_syllabus_to_auth] boolean

Set to true to make the course syllabus public for authenticated users.

course[public_description] string

A publicly visible description of the course.

course[allow_student_wiki_edits] boolean

If true, students will be able to modify the course wiki.

course[allow_wiki_comments] boolean

If true, course members will be able to comment on wiki pages.

course[allow_student_forum_attachments] boolean

If true, students can attach files to forum posts.

course[open_enrollment] boolean

Set to true if the course is open enrollment.

course[self_enrollment] boolean

Set to true if the course is self enrollment.

course[restrict_enrollments_to_course_dates] boolean

Set to true to restrict user enrollments to the start and end dates of the course.

course[term_id] integer

The unique ID of the term to create to course in.

course[sis_course_id] string

The unique SIS identifier.

course[integration_id] string

The unique Integration identifier.

course[hide_final_grades] boolean

If this option is set to true, the totals in student grades summary will be hidden.

course[apply_assignment_group_weights] boolean

Set to true to weight final grade based on assignment groups percentages.

course[time_zone] string

The time zone for the course. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

offer boolean

If this option is set to true, the course will be available to students immediately.

enroll_me boolean

Set to true to enroll the current user as the teacher.

course[default_view] string

The type of page that users will see when they first visit the course

  • 'feed' Recent Activity Dashboard

  • 'modules' Course Modules/Sections Page

  • 'assignments' Course Assignments List

  • 'syllabus' Course Syllabus Page

other types may be added in the future

Allowed values: feed, wiki, modules, syllabus, assignments

course[syllabus_body] string

The syllabus body for the course

course[grading_standard_id] integer

The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course.

course[grade_passback_setting] string

Optional. The grade_passback_setting for the course. Only 'nightly_sync', 'disabled', and '' are allowed

course[course_format] string

Optional. Specifies the format of the course. (Should be 'on_campus', 'online', or 'blended')

enable_sis_reactivation boolean

When true, will first try to re-activate a deleted course with matching sis_course_id if possible.

Returns a Course

Upload a file CoursesController#create_file

POST /api/v1/courses/:course_id/files

Scope: url:POST|/api/v1/courses/:course_id/files

Upload a file to the course.

This API endpoint is the first step in uploading a file to a course. See the File Upload Documentation for details on the file upload workflow.

Only those with the “Manage Files” permission on a course can upload files to the course. By default, this is Teachers, TAs and Designers.

List students CoursesController#students

GET /api/v1/courses/:course_id/students

Scope: url:GET|/api/v1/courses/:course_id/students

Returns the paginated list of students enrolled in this course.

DEPRECATED: Please use the course users endpoint and pass “student” as the enrollment_type.

Returns a list of Users

List users in course CoursesController#users

GET /api/v1/courses/:course_id/users

Scope: url:GET|/api/v1/courses/:course_id/users

GET /api/v1/courses/:course_id/search_users

Scope: url:GET|/api/v1/courses/:course_id/search_users

Returns the paginated list of users in this course. And optionally the user's enrollments in the course.

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.

sort string

When set, sort the results of the search based on the given field.

Allowed values: username, last_login, email, sis_id

enrollment_type[] string

When set, only return users where the user is enrolled as this type. “student_view” implies include[]=test_student. This argument is ignored if enrollment_role is given.

Allowed values: teacher, student, student_view, ta, observer, designer

enrollment_role string

Deprecated When set, only return users enrolled with the specified course-level role. This can be a role created with the Add Role API or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.

enrollment_role_id integer

When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the Add Role API or a built_in role id with type 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.

include[] string
  • “enrollments”:

Optionally include with each Course the user's current and invited enrollments. If the user is enrolled as a student, and the account has permission to manage or view all grades, each enrollment will include a 'grades' key with 'current_score', 'final_score', 'current_grade' and 'final_grade' values.

  • “locked”: Optionally include whether an enrollment is locked.

  • “avatar_url”: Optionally include avatar_url.

  • “bio”: Optionally include each user's bio.

  • “test_student”: Optionally include the course's Test Student,

if present. Default is to not include Test Student.

  • “custom_links”: Optionally include plugin-supplied custom links for each student,

such as analytics information

  • “current_grading_period_scores”: if enrollments is included as

well as this directive, the scores returned in the enrollment will be for the current grading period if there is one. A 'grading_period_id' value will also be included with the scores. if grading_period_id is nil there is no current grading period and the score is a total score.

  • “uuid”: Optionally include the users uuid

Allowed values: enrollments, locked, avatar_url, test_student, bio, custom_links, current_grading_period_scores, uuid

user_id string

If this parameter is given and it corresponds to a user in the course, the page parameter will be ignored and the page containing the specified user will be returned instead.

user_ids[] integer

If included, the course users set will only include users with IDs specified by the param. Note: this will not work in conjunction with the “user_id” argument but multiple user_ids can be included.

enrollment_state[] string

When set, only return users where the enrollment workflow state is of one of the given types. “active” and “invited” enrollments are returned by default.

Allowed values: active, invited, rejected, completed, inactive

Returns a list of Users

List recently logged in students CoursesController#recent_students

GET /api/v1/courses/:course_id/recent_students

Scope: url:GET|/api/v1/courses/:course_id/recent_students

Returns the paginated list of users in this course, ordered by how recently they have logged in. The records include the 'last_login' field which contains a timestamp of the last time that user logged into canvas. The querying user must have the 'View usage reports' permission.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/<course_id>/recent_users
Returns a list of Users

Get single user CoursesController#user

GET /api/v1/courses/:course_id/users/:id

Scope: url:GET|/api/v1/courses/:course_id/users/:id

Return information on a single user.

Accepts the same include[] parameters as the :users: action, and returns a single user with the same fields as that action.

Returns a User

Search for content share users CoursesController#content_share_users

GET /api/v1/courses/:course_id/content_share_users

Scope: url:GET|/api/v1/courses/:course_id/content_share_users

Returns a paginated list of users you can share content with. Requires the content share feature and the user must have the manage content permission for the course.

Request Parameters:

Parameter Type Description
search_term Required string

Term used to find users. Will search available share users with the search term in their name.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/<course_id>/content_share_users \
     -d 'search_term=smith'
Returns a list of Users

Preview processed html CoursesController#preview_html

POST /api/v1/courses/:course_id/preview_html

Scope: url:POST|/api/v1/courses/:course_id/preview_html

Preview html content processed for this course

Request Parameters:

Parameter Type Description
html string

The html content to process

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/preview_html \
     -F 'html=<p><badhtml></badhtml>processed html</p>' \
     -H 'Authorization: Bearer <token>'

Example Response:

{
  "html": "<p>processed html</p>"
}

Course activity stream CoursesController#activity_stream

GET /api/v1/courses/:course_id/activity_stream

Scope: url:GET|/api/v1/courses/:course_id/activity_stream

Returns the current user's course-specific activity stream, paginated.

For full documentation, see the API documentation for the user activity stream, in the user api.

Course activity stream summary CoursesController#activity_stream_summary

GET /api/v1/courses/:course_id/activity_stream/summary

Scope: url:GET|/api/v1/courses/:course_id/activity_stream/summary

Returns a summary of the current user's course-specific activity stream.

For full documentation, see the API documentation for the user activity stream summary, in the user api.

Course TODO items CoursesController#todo_items

GET /api/v1/courses/:course_id/todo

Scope: url:GET|/api/v1/courses/:course_id/todo

Returns the current user's course-specific todo items.

For full documentation, see the API documentation for the user todo items, in the user api.

Delete/Conclude a course CoursesController#destroy

DELETE /api/v1/courses/:id

Scope: url:DELETE|/api/v1/courses/:id

Delete or conclude an existing course

Request Parameters:

Parameter Type Description
event Required string

The action to take on the course.

Allowed values: delete, conclude

Example Response:

{ "delete": "true" }

Get course settings CoursesController#api_settings

GET /api/v1/courses/:course_id/settings

Scope: url:GET|/api/v1/courses/:course_id/settings

Returns some of a course's settings.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/settings \
  -X GET \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "allow_student_discussion_topics": true,
  "allow_student_forum_attachments": false,
  "allow_student_discussion_editing": true,
  "grading_standard_enabled": true,
  "grading_standard_id": 137,
  "allow_student_organized_groups": true,
  "hide_final_grades": false,
  "hide_distribution_graphs": false,
  "lock_all_announcements": true,
  "usage_rights_required": false
}

Update course settings CoursesController#update_settings

PUT /api/v1/courses/:course_id/settings

Scope: url:PUT|/api/v1/courses/:course_id/settings

Can update the following course settings:

Request Parameters:

Parameter Type Description
allow_student_discussion_topics boolean

Let students create discussion topics

allow_student_forum_attachments boolean

Let students attach files to discussions

allow_student_discussion_editing boolean

Let students edit or delete their own discussion posts

allow_student_organized_groups boolean

Let students organize their own groups

filter_speed_grader_by_student_group boolean

Filter SpeedGrader to only the selected student group

hide_final_grades boolean

Hide totals in student grades summary

hide_distribution_graphs boolean

Hide grade distribution graphs from students

lock_all_announcements boolean

Disable comments on announcements

usage_rights_required boolean

Copyright and license information must be provided for files before they are published.

restrict_student_past_view boolean

Restrict students from viewing courses after end date

restrict_student_future_view boolean

Restrict students from viewing courses before start date

show_announcements_on_home_page boolean

Show the most recent announcements on the Course home page (if a Wiki, defaults to five announcements, configurable via home_page_announcement_limit)

home_page_announcement_limit integer

Limit the number of announcements on the home page if enabled via show_announcements_on_home_page

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/settings \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'allow_student_discussion_topics=false'

Return test student for course CoursesController#student_view_student

GET /api/v1/courses/:course_id/student_view_student

Scope: url:GET|/api/v1/courses/:course_id/student_view_student

Returns information for a test student in this course. Creates a test student if one does not already exist for the course. The caller must have permission to access the course's student view.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/student_view_student \
  -X GET \
  -H 'Authorization: Bearer <token>'
Returns a User

Get a single course CoursesController#show

GET /api/v1/courses/:id

Scope: url:GET|/api/v1/courses/:id

GET /api/v1/accounts/:account_id/courses/:id

Scope: url:GET|/api/v1/accounts/:account_id/courses/:id

Return information on a single course.

Accepts the same include[] parameters as the list action plus:

Request Parameters:

Parameter Type Description
include[] string
  • “all_courses”: Also search recently deleted courses.

  • “permissions”: Include permissions the current user has for the course.

  • “observed_users”: include observed users in the enrollments

  • “course_image”: Optional course image data for when there is a course image and the course image feature flag has been enabled

  • “concluded”: Optional information to include with each Course. Indicates whether the course has been concluded, taking course and term dates into account.

Allowed values: needs_grading_count, syllabus_body, public_description, total_scores, current_grading_period_scores, term, account, course_progress, sections, storage_quota_used_mb, total_students, passback_status, favorites, teachers, observed_users, all_courses, permissions, observed_users, course_image, concluded

teacher_limit integer

The maximum number of teacher enrollments to show. If the course contains more teachers than this, instead of giving the teacher enrollments, the count of teachers will be given under a teacher_count key.

Returns a Course

Update a course CoursesController#update

PUT /api/v1/courses/:id

Scope: url:PUT|/api/v1/courses/:id

Update an existing course.

Arguments are the same as Courses#create, with a few exceptions (enroll_me).

If a user has content management rights, but not full course editing rights, the only attribute editable through this endpoint will be “syllabus_body”

Request Parameters:

Parameter Type Description
course[account_id] integer

The unique ID of the account to move the course to.

course[name] string

The name of the course. If omitted, the course will be named “Unnamed Course.”

course[course_code] string

The course code for the course.

course[start_at] DateTime

Course start date in ISO8601 format, e.g. 2011-01-01T01:00Z

course[end_at] DateTime

Course end date in ISO8601 format. e.g. 2011-01-01T01:00Z

course[license] string

The name of the licensing. Should be one of the following abbreviations (a descriptive name is included in parenthesis for reference):

  • 'private' (Private Copyrighted)

  • 'cc_by_nc_nd' (CC Attribution Non-Commercial No Derivatives)

  • 'cc_by_nc_sa' (CC Attribution Non-Commercial Share Alike)

  • 'cc_by_nc' (CC Attribution Non-Commercial)

  • 'cc_by_nd' (CC Attribution No Derivatives)

  • 'cc_by_sa' (CC Attribution Share Alike)

  • 'cc_by' (CC Attribution)

  • 'public_domain' (Public Domain).

course[is_public] boolean

Set to true if course is public to both authenticated and unauthenticated users.

course[is_public_to_auth_users] boolean

Set to true if course is public only to authenticated users.

course[public_syllabus] boolean

Set to true to make the course syllabus public.

course[public_syllabus_to_auth] boolean

Set to true to make the course syllabus to public for authenticated users.

course[public_description] string

A publicly visible description of the course.

course[allow_student_wiki_edits] boolean

If true, students will be able to modify the course wiki.

course[allow_wiki_comments] boolean

If true, course members will be able to comment on wiki pages.

course[allow_student_forum_attachments] boolean

If true, students can attach files to forum posts.

course[open_enrollment] boolean

Set to true if the course is open enrollment.

course[self_enrollment] boolean

Set to true if the course is self enrollment.

course[restrict_enrollments_to_course_dates] boolean

Set to true to restrict user enrollments to the start and end dates of the course.

course[term_id] integer

The unique ID of the term to create to course in.

course[sis_course_id] string

The unique SIS identifier.

course[integration_id] string

The unique Integration identifier.

course[hide_final_grades] boolean

If this option is set to true, the totals in student grades summary will be hidden.

course[time_zone] string

The time zone for the course. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

course[apply_assignment_group_weights] boolean

Set to true to weight final grade based on assignment groups percentages.

course[storage_quota_mb] integer

Set the storage quota for the course, in megabytes. The caller must have the “Manage storage quotas” account permission.

offer boolean

If this option is set to true, the course will be available to students immediately.

course[event] string

The action to take on each course.

  • 'claim' makes a course no longer visible to students. This action is also called “unpublish” on the web site. A course cannot be unpublished if students have received graded submissions.

  • 'offer' makes a course visible to students. This action is also called “publish” on the web site.

  • 'conclude' prevents future enrollments and makes a course read-only for all participants. The course still appears in prior-enrollment lists.

  • 'delete' completely removes the course from the web site (including course menus and prior-enrollment lists). All enrollments are deleted. Course content may be physically deleted at a future date.

  • 'undelete' attempts to recover a course that has been deleted. This action requires account administrative rights. (Recovery is not guaranteed; please conclude rather than delete a course if there is any possibility the course will be used again.) The recovered course will be unpublished. Deleted enrollments will not be recovered.

Allowed values: claim, offer, conclude, delete, undelete

course[default_view] string

The type of page that users will see when they first visit the course

  • 'feed' Recent Activity Dashboard

  • 'wiki' Wiki Front Page

  • 'modules' Course Modules/Sections Page

  • 'assignments' Course Assignments List

  • 'syllabus' Course Syllabus Page

other types may be added in the future

Allowed values: feed, wiki, modules, syllabus, assignments

course[syllabus_body] string

The syllabus body for the course

course[syllabus_course_summary] boolean

Optional. Indicates whether the Course Summary (consisting of the course's assignments and calendar events) is displayed on the syllabus page. Defaults to true.

course[grading_standard_id] integer

The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course.

course[grade_passback_setting] string

Optional. The grade_passback_setting for the course. Only 'nightly_sync' and '' are allowed

course[course_format] string

Optional. Specifies the format of the course. (Should be either 'on_campus' or 'online')

course[image_id] integer

This is a file ID corresponding to an image file in the course that will be used as the course image. This will clear the course's image_url setting if set. If you attempt to provide image_url and image_id in a request it will fail.

course[image_url] string

This is a URL to an image to be used as the course image. This will clear the course's image_id setting if set. If you attempt to provide image_url and image_id in a request it will fail.

course[remove_image] boolean

If this option is set to true, the course image url and course image ID are both set to nil

course[blueprint] boolean

Sets the course as a blueprint course.

course[blueprint_restrictions] BlueprintRestriction

Sets a default set to apply to blueprint course objects when restricted, unless use_blueprint_restrictions_by_object_type is enabled. See the Blueprint Restriction documentation

course[use_blueprint_restrictions_by_object_type] boolean

When enabled, the blueprint_restrictions parameter will be ignored in favor of the blueprint_restrictions_by_object_type parameter

course[blueprint_restrictions_by_object_type] multiple BlueprintRestrictions

Allows setting multiple Blueprint Restriction to apply to blueprint course objects of the matching type when restricted. The possible object types are “assignment”, “attachment”, “discussion_topic”, “quiz” and “wiki_page”. Example usage:

course[blueprint_restrictions_by_object_type][assignment][content]=1

Example Request:

curl https://<canvas>/api/v1/courses/<course_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'course[name]=New course name' \
  -d 'course[start_at]=2012-05-05T00:00:00Z'

Example Response:

{
  "name": "New course name",
  "course_code": "COURSE-001",
  "start_at": "2012-05-05T00:00:00Z",
  "end_at": "2012-08-05T23:59:59Z",
  "sis_course_id": "12345"
}

Update courses CoursesController#batch_update

PUT /api/v1/accounts/:account_id/courses

Scope: url:PUT|/api/v1/accounts/:account_id/courses

Update multiple courses in an account. Operates asynchronously; use the progress endpoint to query the status of an operation.

The action to take on each course. Must be one of 'offer', 'conclude', 'delete', or 'undelete'.

* 'offer' makes a course visible to students. This action is also called "publish" on the web site.
* 'conclude' prevents future enrollments and makes a course read-only for all participants. The course still appears
  in prior-enrollment lists.
* 'delete' completely removes the course from the web site (including course menus and prior-enrollment lists).
  All enrollments are deleted. Course content may be physically deleted at a future date.
* 'undelete' attempts to recover a course that has been deleted. (Recovery is not guaranteed; please conclude
  rather than delete a course if there is any possibility the course will be used again.) The recovered course
  will be unpublished. Deleted enrollments will not be recovered.

Request Parameters:

Parameter Type Description
course_ids[] Required string

List of ids of courses to update. At most 500 courses may be updated in one call.

event Required string

no description

Allowed values: offer, conclude, delete, undelete

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/courses \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'event=offer' \
  -d 'course_ids[]=1' \
  -d 'course_ids[]=2'
Returns a Progress

Reset a course CoursesController#reset_content

POST /api/v1/courses/:course_id/reset_content

Scope: url:POST|/api/v1/courses/:course_id/reset_content

Deletes the current course, and creates a new equivalent course with no content, but all sections and users moved over.

Returns a Course

Get effective due dates CoursesController#effective_due_dates

GET /api/v1/courses/:course_id/effective_due_dates

Scope: url:GET|/api/v1/courses/:course_id/effective_due_dates

For each assignment in the course, returns each assigned student's ID and their corresponding due date along with some grading period data. Returns a collection with keys representing assignment IDs and values as a collection containing keys representing student IDs and values representing the student's effective due_at, the grading_period_id of which the due_at falls in, and whether or not the grading period is closed (in_closed_grading_period)

The list of assignment IDs for which effective student due dates are requested. If not provided, all assignments in the course will be used.

Request Parameters:

Parameter Type Description
assignment_ids[] string

no description

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/effective_due_dates
  -X GET \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "1": {
     "14": { "due_at": "2015-09-05", "grading_period_id": null, "in_closed_grading_period": false },
     "15": { due_at: null, "grading_period_id": 3, "in_closed_grading_period": true }
  },
  "2": {
     "14": { "due_at": "2015-08-05", "grading_period_id": 3, "in_closed_grading_period": true }
  }
}

Permissions CoursesController#permissions

GET /api/v1/courses/:course_id/permissions

Scope: url:GET|/api/v1/courses/:course_id/permissions

Returns permission information for the calling user in the given course. See also the Account and Group counterparts.

Request Parameters:

Parameter Type Description
permissions[] string

List of permissions to check against the authenticated user. Permission names are documented in the Create a role endpoint.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/permissions \
  -H 'Authorization: Bearer <token>' \
  -d 'permissions[]=manage_grades'
  -d 'permissions[]=send_messages'

Example Response:

{'manage_grades': 'false', 'send_messages': 'true'}

Get course copy status ContentImportsController#copy_course_status

GET /api/v1/courses/:course_id/course_copy/:id

Scope: url:GET|/api/v1/courses/:course_id/course_copy/:id

DEPRECATED: Please use the Content Migrations API

Retrieve the status of a course copy

API response field:

  • id

    The unique identifier for the course copy.

  • created_at

    The time that the copy was initiated.

  • progress

    The progress of the copy as an integer. It is null before the copying starts, and 100 when finished.

  • workflow_state

    The current status of the course copy. Possible values: “created”, “started”, “completed”, “failed”

  • status_url

    The url for the course copy status API endpoint.

Example Response:

{'progress':100, 'workflow_state':'completed', 'id':257, 'created_at':'2011-11-17T16:50:06Z', 'status_url':'/api/v1/courses/9457/course_copy/257'}

Copy course content ContentImportsController#copy_course_content

POST /api/v1/courses/:course_id/course_copy

Scope: url:POST|/api/v1/courses/:course_id/course_copy

DEPRECATED: Please use the Content Migrations API

Copies content from one course into another. The default is to copy all course content. You can control specific types to copy by using either the 'except' option or the 'only' option.

The response is the same as the course copy status endpoint

Request Parameters:

Parameter Type Description
source_course string

ID or SIS-ID of the course to copy the content from

except[] string

A list of the course content types to exclude, all areas not listed will be copied.

Allowed values: course_settings, assignments, external_tools, files, topics, calendar_events, quizzes, wiki_pages, modules, outcomes

only[] string

A list of the course content types to copy, all areas not listed will not be copied.

Allowed values: course_settings, assignments, external_tools, files, topics, calendar_events, quizzes, wiki_pages, modules, outcomes