Courses API

API for accessing course information.

A Course object looks like:

{
    // the unique identifier for the course
    id: 370663,

    // the SIS identifier for the course, if defined
    sis_course_id: null,

    // 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 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: null,

    // A list of enrollments linking the current user to the course.
    // for student enrollments, grading information may be included
    // if include[]=total_scores
    enrollments: [
      {
        type: student,
        role: StudentEnrollment,
        computed_final_score: 41.5,
        computed_current_score: 90,
        computed_final_grade: 'F'
        computed_current_grade: 'A-',
      }
    ],

    // course calendar
    calendar: {
      ics: "https:\/\/canvas.instructure.com\/feeds\/calendars\/course_abcdef.ics"
    }

    // 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 name of the enrollment term for the course
    // returned only if include[]=term
    term: {
      id: 1,
      name: 'Default Term',
      start_at: "2012-06-01T00:00:00-06:00",
      end_at: null
    }

}

List your courses CoursesController#index

GET /api/v1/courses

Returns the list of active courses for the current user.

Request Parameters:

  • enrollment_type
    optional, "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

    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[]
    "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.

  • include[]
    "syllabus_body"

    Optional information to include with each Course.

    When syllabus_body is given the user-generated html for the course syllabus is returned.

  • include[]
    "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.

  • include[]
    "term"

    Optional information to include with each Course.

    When term is given, the information for the enrollment term for each course is returned.

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]
    String
    optional

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

  • course[course_code]
    String
    optional

    The course code for the course.

  • course[start_at]
    Datetime
    optional

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

  • course[end_at]
    Datetime
    optional

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

  • course[license]
    String
    optional

    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
    optional

    Set to true if course if public.

  • course[public_syllabus]
    Boolean
    optional

    Set to true to make the course syllabus public.

  • course[public_description]
    String
    optional

    A publicly visible description of the course.

  • course[allow_student_wiki_edits]
    Boolean
    optional

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

  • course[allow_wiki_comments]
    Boolean
    optional

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

  • course[allow_student_forum_attachments]
    Boolean
    optional

    If true, students can attach files to forum posts.

  • course[open_enrollment]
    Boolean
    optional

    Set to true if the course is open enrollment.

  • course[self_enrollment]
    Boolean
    optional

    Set to true if the course is self enrollment.

  • course[restrict_enrollments_to_course_dates]
    Boolean
    optional

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

  • course[enroll_me]
    Boolean
    optional

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

  • course[sis_course_id]
    String
    optional

    The unique SIS identifier.

  • course[hide_final_grades]
    Boolean
    optional

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

  • offer
    Boolean
    optional

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

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 CoursesController#users

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

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

Request Parameters:

  • enrollment_type
    optional, "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

    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[]
    "email"

    Optional user email.

  • include[]
    "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.

  • include[]
    "locked"

    Optionally include whether an enrollment is locked.

  • include[]
    "avatar_url"

    Optionally include avatar_url.

  • include[]
    "test_student"

    Optionally include the course's Test Student,

    if present. Default is to not include Test Student.

  • user_id
    optional

    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

Search users CoursesController#search_users

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

Returns a list of users in this course that match a search term.

Request Parameters:

  • search_term

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

  • enrollment_type
    optional, "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

    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[]

    The same as the List Users API

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

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

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 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. available options are 'delete' and 'conclude.'

Update course settings CoursesController#update_settings

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

Can update the following course settings:

  • `allow_student_discussion_topics` (true|false)

  • `allow_student_forum_attachments` (true|false)

  • `allow_student_discussion_editing` (true|false)

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[]
    "all_courses"

    Also search recently deleted courses

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

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

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

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 possible items for 'except' and 'only' are: "course_settings", "assignments", "external_tools", "files", "topics", "calendar_events", "quizzes", "wiki_pages", "modules", "outcomes"

The response is the same as the course copy status endpoint

Request Parameters:

  • source_course

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

  • except[]

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

  • only[]

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