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": ""
}

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
  "sis_course_id": "",
  
  //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 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",
  
  //A list of enrollments linking the current user to the course. for student
  //enrollments, grading information may be included if include[]=total_scores
  "enrollments": "",
  
  //course calendar
  "calendar": "",
  
  //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": "",
  
  //optional (beta): information on progress through the course returned only if
  //include[]=course_progress
  "course_progress": "",
  
  //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}",
  
  "is_public": "true",
  
  "public_syllabus": "true",
  
  "public_description": "Come one, come all to InstructureCon 2012!",
  
  "storage_quota_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"
}

List your courses CoursesController#index

GET /api/v1/courses

Returns the list of active courses for the current user.

Request Parameters:

  • enrollment_type
    Optional, String, "teacher"|"student"|"ta"|"observer"|"designer"

    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.

  • enrollment_role
    Optional, String

    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'.

  • include[]
    String, "needs_grading_count"|"syllabus_body"|"total_scores"|"term"|"course_progress"
    • "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.

    • "total_scores": Optional information to include with each Course. When total_scores is given, any enrollments with type 'student' will also include the fields 'calculated_current_score', 'calculated_final_score', 'calculated_current_grade', and 'calculated_final_grade'. calculated_current_score is the student's score in the course, ignoring ungraded assignments. calculated_final_score is the student's score in the course including ungraded assignments with a score of 0. calculated_current_grade is the letter grade equivalent of calculated_current_score (if available). calculated_final_grade is the letter grade equivalent of calculated_final_score (if available). This argument is ignored if the course is configured to hide final grades.

    • "term": Optional information to include with each Course. When term is given, the information for the enrollment term 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.

  • state[]
    Optional, String, "unpublished"|"available"|"completed"|"deleted"

    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

Returns a list of Courses

Create a new course CoursesController#create

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

Create a new course

Request Parameters:

  • account_id
    Integer

    The unique ID of the account to create to course under.

  • course[name]
    Optional, String

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

  • course[course_code]
    Optional, String

    The course code for the course.

  • course[start_at]
    Optional, DateTime

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

  • course[end_at]
    Optional, DateTime

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

  • course[license]
    Optional, 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]
    Optional, Boolean

    Set to true if course if public.

  • course[public_syllabus]
    Optional, Boolean

    Set to true to make the course syllabus public.

  • course[public_description]
    Optional, String

    A publicly visible description of the course.

  • course[allow_student_wiki_edits]
    Optional, Boolean

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

  • course[allow_wiki_comments]
    Optional, Boolean

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

  • course[allow_student_forum_attachments]
    Optional, Boolean

    If true, students can attach files to forum posts.

  • course[open_enrollment]
    Optional, Boolean

    Set to true if the course is open enrollment.

  • course[self_enrollment]
    Optional, Boolean

    Set to true if the course is self enrollment.

  • course[restrict_enrollments_to_course_dates]
    Optional, Boolean

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

  • course[enroll_me]
    Optional, Boolean

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

  • course[term_id]
    Optional, Integer

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

  • course[sis_course_id]
    Optional, String

    The unique SIS identifier.

  • course[hide_final_grades]
    Optional, Boolean

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

  • course[apply_assignment_group_weights]
    Optional, Boolean

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

  • offer
    Optional, Boolean

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

  • course[syllabus_body]
    Optional, String

    The syllabus body for the course

Returns a Course

Upload a file CoursesController#create_file

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

Returns the 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

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

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

Request Parameters:

  • search_term
    Optional, String

    The partial name or full ID of the users to match and return in the results list.

  • enrollment_type
    Optional, String, "teacher"|"student"|"ta"|"observer"|"designer"

    When set, only return users where the user is enrolled as this type. This argument is ignored if enrollment_role is given.

  • enrollment_role
    Optional, String

    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'.

  • include[]
    String, "email"|"enrollments"|"locked"|"avatar_url"|"test_student"
    • "email": Optional user email.

    • "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.

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

    if present. Default is to not include Test Student.

  • user_id
    Optional, String

    If included, the user will be queried and if the user is part of the users set, the page parameter will be modified so that the page containing user_id will be returned.

Returns a list of Users

List recently logged in students CoursesController#recent_students

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

Returns the 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

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

Preview processed html CoursesController#preview_html

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

Preview html content processed for this course

Request Parameters:

  • html

    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

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

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

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.

Conclude a course CoursesController#destroy

DELETE /api/v1/courses/:id

Delete or conclude an existing course

Request Parameters:

  • event
    String, "delete"|"conclude"

    The action to take on the course.

Get course settings CoursesController#settings

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
}

Update course settings CoursesController#update_settings

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

Can update the following course settings:

Request Parameters:

  • allow_student_discussion_topics
    Boolean
  • allow_student_forum_attachments
    Boolean
  • allow_student_discussion_editing
    Boolean

Example Request:

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

Get a single course CoursesController#show

GET /api/v1/courses/:id

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:

  • include[]
    String, "all_courses"|"permissions"
    • "all_courses": Also search recently deleted courses.

    • "permissions": Include permissions the current user has for the course.

Returns a Course

Update a course CoursesController#update

PUT /api/v1/courses/:id

Update an existing course.

For possible arguments, see the Courses#create documentation (note: the enroll_me param is not allowed in the update action).

Additional arguments available for Courses#update

Request Parameters:

  • course[grading_standard_id]
    Optional, 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.

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

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

Request Parameters:

  • course_ids[]

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

  • event

    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.

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

Get course copy status ContentImportsController#copy_course_status

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

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:

  • source_course
    String

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

  • except[]
    String, "course_settings"|"assignments"|"external_tools"|"files"|"topics"|"calendar_events"|"quizzes"|"wiki_pages"|"modules"|"outcomes"

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

  • only[]
    String, "course_settings"|"assignments"|"external_tools"|"files"|"topics"|"calendar_events"|"quizzes"|"wiki_pages"|"modules"|"outcomes"

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