All API Resources

Show an access token TokensController#show

GET /api/v1/users/:user_id/tokens/:id

Scope: url:GET|/api/v1/users/:user_id/tokens/:id

The ID can be the actual database ID of the token, or the ‘token_hint’ value.

Create an access token TokensController#create

POST /api/v1/users/:user_id/tokens

Scope: url:POST|/api/v1/users/:user_id/tokens

Create a new access token for the specified user. If the user is not the current user, the token will be created as “pending”, and must be activated by the user before it can be used.

Request Parameters:

Parameter Type Description
token[purpose] Required string

The purpose of the token.

token[expires_at] DateTime

The time at which the token will expire.

token[scopes][] Array

The scopes to associate with the token.

Update an access token TokensController#update

PUT /api/v1/users/:user_id/tokens/:id

Scope: url:PUT|/api/v1/users/:user_id/tokens/:id

Update an existing access token.

The ID can be the actual database ID of the token, or the ‘token_hint’ value.

Regenerating an expired token requires a new expiration date.

Request Parameters:

Parameter Type Description
token[purpose] string

The purpose of the token.

token[expires_at] DateTime

The time at which the token will expire.

token[scopes][] Array

The scopes to associate with the token.

token[regenerate] boolean

Regenerate the actual token.

Delete an access token TokensController#destroy

DELETE /api/v1/users/:user_id/tokens/:id

Scope: url:DELETE|/api/v1/users/:user_id/tokens/:id

The ID can be the actual database ID of the token, or the ‘token_hint’ value.

List available account calendars AccountCalendarsApiController#index

GET /api/v1/account_calendars

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

Returns a paginated list of account calendars available to the current user. Includes visible account calendars where the user has an account association.

Request Parameters:

Parameter Type Description
search_term string

When included, searches available account calendars for the term. Returns matching results. Term must be at least 2 characters.

Example Request:

curl https://<canvas>/api/v1/account_calendars \
  -H 'Authorization: Bearer <token>'
Returns a list of AccountCalendar objects

Get a single account calendar AccountCalendarsApiController#show

GET /api/v1/account_calendars/:account_id

Scope: url:GET|/api/v1/account_calendars/:account_id

Get details about a specific account calendar.

Example Request:

curl https://<canvas>/api/v1/account_calendars/204 \
  -H 'Authorization: Bearer <token>'
Returns an AccountCalendar object

Update a calendar AccountCalendarsApiController#update

PUT /api/v1/account_calendars/:account_id

Scope: url:PUT|/api/v1/account_calendars/:account_id

Set an account calendar’s visibility and auto_subscribe values. Requires the ‘manage_account_calendar_visibility` permission on the account.

Request Parameters:

Parameter Type Description
visible boolean

Allow administrators with ‘manage_account_calendar_events` permission to create events on this calendar, and allow users to view this calendar and its events.

auto_subscribe boolean

When true, users will automatically see events from this account in their calendar, even if they haven’t manually added that calendar.

Example Request:

curl https://<canvas>/api/v1/account_calendars/204 \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'visible=false' \
  -d 'auto_subscribe=false'
Returns an AccountCalendar object

Update several calendars AccountCalendarsApiController#bulk_update

PUT /api/v1/accounts/:account_id/account_calendars

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

Set visibility and/or auto_subscribe on many calendars simultaneously. Requires the ‘manage_account_calendar_visibility` permission on the account.

Accepts a JSON array of objects containing 2-3 keys each: ‘id` (the account’s id, required), ‘visible` (a boolean indicating whether the account calendar is visible), and `auto_subscribe` (a boolean indicating whether users should see these events in their calendar without manually subscribing).

Returns the count of updated accounts.

Example Request:

curl https://<canvas>/api/v1/accounts/1/account_calendars \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  --data '[{"id": 1, "visible": true, "auto_subscribe": false}, {"id": 13, "visible": false, "auto_subscribe": true}]'

List all account calendars AccountCalendarsApiController#all_calendars

GET /api/v1/accounts/:account_id/account_calendars

Scope: url:GET|/api/v1/accounts/:account_id/account_calendars

Returns a paginated list of account calendars for the provided account and its first level of sub-accounts. Includes hidden calendars in the response. Requires the ‘manage_account_calendar_visibility` permission.

Request Parameters:

Parameter Type Description
search_term string

When included, searches all descendent accounts of provided account for the term. Returns matching results. Term must be at least 2 characters. Can be combined with a filter value.

filter string

When included, only returns calendars that are either visible or hidden. Can be combined with a search term.

Allowed values: visible, hidden

Example Request:

curl https://<canvas>/api/v1/accounts/1/account_calendars \
  -H 'Authorization: Bearer <token>'
Returns a list of AccountCalendar objects

Count of all visible account calendars AccountCalendarsApiController#visible_calendars_count

GET /api/v1/accounts/:account_id/visible_calendars_count

Scope: url:GET|/api/v1/accounts/:account_id/visible_calendars_count

Returns the number of visible account calendars.

Example Request:

curl https://<canvas>/api/v1/accounts/1/visible_calendars_count \
  -H 'Authorization: Bearer <token>'

Search account domains

GET /api/v1/accounts/search

Scope: url:GET|/api/v1/accounts/search

Returns a list of up to 5 matching account domains

Partial match on name / domain are supported

Request Parameters:

Parameter Type Description
name string

campus name

domain string

no description

latitude number

no description

longitude number

no description

Example Request:

curl https://<canvas>/api/v1/accounts/search \
  -G -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d 'name=utah'

Example Response:

[
  {
    "name": "University of Utah",
    "domain": "utah.edu",
    "distance": null, // distance is always nil, but preserved in the api response for backwards compatibility
    "authentication_provider": "canvas", // which authentication_provider param to pass to the oauth flow; may be NULL
  },
  ...
]

Index of active global notification for the user AccountNotificationsController#user_index

GET /api/v1/accounts/:account_id/account_notifications

Scope: url:GET|/api/v1/accounts/:account_id/account_notifications

Returns a list of all global notifications in the account for the current user Any notifications that have been closed by the user will not be returned, unless a include_past parameter is passed in as true. Admins can request all global notifications for the account by passing in an include_all parameter.

Request Parameters:

Parameter Type Description
include_past boolean

Include past and dismissed global announcements.

include_all boolean

Include all global announcements, regardless of user’s role. Only available to account admins.

Example Request:

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/users/self/account_notifications
Returns a list of AccountNotification objects

Show a global notification AccountNotificationsController#show

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

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

Returns a global notification for the current user A notification that has been closed by the user will not be returned

Example Request:

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/users/self/account_notifications/4
Returns an AccountNotification object

Close notification for user AccountNotificationsController#user_close_notification

DELETE /api/v1/accounts/:account_id/account_notifications/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/account_notifications/:id

If the current user no long wants to see this notification it can be excused with this call

Example Request:

curl -X DELETE -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/users/self/account_notifications/4
Returns an AccountNotification object

Create a global notification AccountNotificationsController#create

POST /api/v1/accounts/:account_id/account_notifications

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

Create and return a new global notification for an account.

Request Parameters:

Parameter Type Description
account_notification[subject] Required string

The subject of the notification.

account_notification[message] Required string

The message body of the notification.

account_notification[start_at] Required DateTime

The start date and time of the notification in ISO8601 format. e.g. 2014-01-01T01:00Z

account_notification[end_at] Required DateTime

The end date and time of the notification in ISO8601 format. e.g. 2014-01-01T01:00Z

account_notification[icon] string

The icon to display with the notification. Note: Defaults to warning.

Allowed values: warning, information, question, error, calendar

account_notification_roles[] string

The role(s) to send global notification to. Note: ommitting this field will send to everyone Example:

account_notification_roles: ["StudentEnrollment", "TeacherEnrollment"]

Example Request:

curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/account_notifications \
-d 'account_notification[subject]=New notification' \
-d 'account_notification[start_at]=2014-01-01T00:00:00Z' \
-d 'account_notification[end_at]=2014-02-01T00:00:00Z' \
-d 'account_notification[message]=This is a global notification'

Example Response:

{
  "subject": "New notification",
  "start_at": "2014-01-01T00:00:00Z",
  "end_at": "2014-02-01T00:00:00Z",
  "message": "This is a global notification"
}

Update a global notification AccountNotificationsController#update

PUT /api/v1/accounts/:account_id/account_notifications/:id

Scope: url:PUT|/api/v1/accounts/:account_id/account_notifications/:id

Update global notification for an account.

Request Parameters:

Parameter Type Description
account_notification[subject] string

The subject of the notification.

account_notification[message] string

The message body of the notification.

account_notification[start_at] DateTime

The start date and time of the notification in ISO8601 format. e.g. 2014-01-01T01:00Z

account_notification[end_at] DateTime

The end date and time of the notification in ISO8601 format. e.g. 2014-01-01T01:00Z

account_notification[icon] string

The icon to display with the notification.

Allowed values: warning, information, question, error, calendar

account_notification_roles[] string

The role(s) to send global notification to. Note: ommitting this field will send to everyone Example:

account_notification_roles: ["StudentEnrollment", "TeacherEnrollment"]

Example Request:

curl -X PUT -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/account_notifications/1 \
-d 'account_notification[subject]=New notification' \
-d 'account_notification[start_at]=2014-01-01T00:00:00Z' \
-d 'account_notification[end_at]=2014-02-01T00:00:00Z' \
-d 'account_notification[message]=This is a global notification'

Example Response:

{
  "subject": "New notification",
  "start_at": "2014-01-01T00:00:00Z",
  "end_at": "2014-02-01T00:00:00Z",
  "message": "This is a global notification"
}

List Available Reports AccountReportsController#available_reports

GET /api/v1/accounts/:account_id/reports

Scope: url:GET|/api/v1/accounts/:account_id/reports

Returns a paginated list of reports for the current context.

API response field:

  • name

    The name of the report.

  • parameters

    The parameters will vary for each report

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/accounts/<account_id>/reports/

Example Response:

[
  {
    "report":"student_assignment_outcome_map_csv",
    "title":"Student Competency",
    "parameters":null
  },
  {
    "report":"grade_export_csv",
    "title":"Grade Export",
    "parameters":{
      "term":{
        "description":"The canvas id of the term to get grades from",
        "required":true
      }
    }
  }
]

Start a Report AccountReportsController#create

POST /api/v1/accounts/:account_id/reports/:report

Scope: url:POST|/api/v1/accounts/:account_id/reports/:report

Generates a report instance for the account. Note that “report” in the request must match one of the available report names. To fetch a list of available report names and parameters for each report (including whether or not those parameters are required), see List Available Reports.

Request Parameters:

Parameter Type Description
parameters string

The parameters will vary for each report. To fetch a list of available parameters for each report, see List Available Reports. A few example parameters have been provided below. Note that the example parameters provided below may not be valid for every report.

parameters[skip_message] boolean

If true, no message will be sent to the user upon completion of the report.

parameters[course_id] integer

The id of the course to report on. Note: this parameter has been listed to serve as an example and may not be valid for every report.

parameters[users] boolean

If true, user data will be included. If false, user data will be omitted. Note: this parameter has been listed to serve as an example and may not be valid for every report.

Example Request:

curl -X POST \
     https://<canvas>/api/v1/accounts/1/reports/provisioning_csv \
     -H 'Authorization: Bearer <token>' \
     -H 'Content-Type: multipart/form-data' \
     -F 'parameters[users]=true' \
     -F 'parameters[courses]=true' \
     -F 'parameters[enrollments]=true'
Returns a Report object

Index of Reports AccountReportsController#index

GET /api/v1/accounts/:account_id/reports/:report

Scope: url:GET|/api/v1/accounts/:account_id/reports/:report

Shows all reports that have been run for the account of a specific type.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/accounts/<account_id>/reports/<report_type>
Returns a list of Report objects

Status of a Report AccountReportsController#show

GET /api/v1/accounts/:account_id/reports/:report/:id

Scope: url:GET|/api/v1/accounts/:account_id/reports/:report/:id

Returns the status of a report.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/accounts/<account_id>/reports/<report_type>/<report_id>
Returns a Report object

Delete a Report AccountReportsController#destroy

DELETE /api/v1/accounts/:account_id/reports/:report/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/reports/:report/:id

Deletes a generated report instance.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     -X DELETE \
     https://<canvas>/api/v1/accounts/<account_id>/reports/<report_type>/<id>
Returns a Report object

Abort a Report AccountReportsController#abort

PUT /api/v1/accounts/:account_id/reports/:report/:id/abort

Scope: url:PUT|/api/v1/accounts/:account_id/reports/:report/:id/abort

Abort a report in progress

Example Request:

curl -H 'Authorization: Bearer <token>' \
     -X PUT \
     https://<canvas>/api/v1/accounts/<account_id>/reports/<report_type>/<id>/abort
Returns a Report object

List accounts AccountsController#index

GET /api/v1/accounts

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

A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in.

Request Parameters:

Parameter Type Description
include[] string

Array of additional information to include.

“lti_guid”

the ‘tool_consumer_instance_guid’ that will be sent for this account on LTI launches

“registration_settings”

returns info about the privacy policy and terms of use

“services”

returns services and whether they are enabled (requires account management permissions)

“course_count”

returns the number of courses directly under each account

“sub_account_count”

returns the number of sub-accounts directly under each account

Allowed values: lti_guid, registration_settings, services, course_count, sub_account_count

Returns a list of Account objects

Get accounts that admins can manage AccountsController#manageable_accounts

GET /api/v1/manageable_accounts

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

A paginated list of accounts where the current user has permission to create or manage courses. List will be empty for students and teachers as only admins can view which accounts they are in.

Returns a list of Account objects

Get accounts that users can create courses in AccountsController#course_creation_accounts

GET /api/v1/course_creation_accounts

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

A paginated list of accounts where the current user has permission to create courses.

Returns a list of Account objects

List accounts for course admins AccountsController#course_accounts

GET /api/v1/course_accounts

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

A paginated list of accounts that the current user can view through their admin course enrollments. (Teacher, TA, or designer enrollments). Only returns “id”, “name”, “workflow_state”, “root_account_id” and “parent_account_id”

Returns a list of Account objects

Get a single account AccountsController#show

GET /api/v1/accounts/:id

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

Retrieve information on an individual account, given by id or sis sis_account_id.

Returns an Account object

Settings AccountsController#show_settings

GET /api/v1/accounts/:account_id/settings

Scope: url:GET|/api/v1/accounts/:account_id/settings

Returns a JSON object containing a subset of settings for the specified account. It’s possible an empty set will be returned if no settings are applicable. The caller must be an Account admin with the manage_account_settings permission.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/settings \
  -H 'Authorization: Bearer <token>'

Example Response:

{"microsoft_sync_enabled": true, "microsoft_sync_login_attribute_suffix": false}

List environment settings AccountsController#environment

GET /api/v1/settings/environment

Scope: url:GET|/api/v1/settings/environment

Return a hash of global settings for the root account This is the same information supplied to the web interface as ENV.SETTINGS.

Example Request:

curl 'http://<canvas>/api/v1/settings/environment' \
  -H "Authorization: Bearer <token>"

Example Response:

{ "calendar_contexts_limit": 10, "open_registration": false, ...}

Permissions AccountsController#permissions

GET /api/v1/accounts/:account_id/permissions

Scope: url:GET|/api/v1/accounts/:account_id/permissions

Returns permission information for the calling user and the given account. You may use ‘self` as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account.

See also the Course 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/accounts/self/permissions \
  -H 'Authorization: Bearer <token>' \
  -d 'permissions[]=manage_account_memberships' \
  -d 'permissions[]=become_user'

Example Response:

{'manage_account_memberships': 'false', 'become_user': 'true'}

Get the sub-accounts of an account AccountsController#sub_accounts

GET /api/v1/accounts/:account_id/sub_accounts

Scope: url:GET|/api/v1/accounts/:account_id/sub_accounts

List accounts that are sub-accounts of the given account.

Request Parameters:

Parameter Type Description
recursive boolean

If true, the entire account tree underneath this account will be returned (though still paginated). If false, only direct sub-accounts of this account will be returned. Defaults to false.

include[] string

Array of additional information to include.

“course_count”

returns the number of courses directly under each account

“sub_account_count”

returns the number of sub-accounts directly under each account

Allowed values: course_count, sub_account_count

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/sub_accounts \
     -H 'Authorization: Bearer <token>'
Returns a list of Account objects

Get the Terms of Service AccountsController#terms_of_service

GET /api/v1/accounts/:account_id/terms_of_service

Scope: url:GET|/api/v1/accounts/:account_id/terms_of_service

Returns the terms of service for that account

Returns a TermsOfService object

Get help links AccountsController#help_links

GET /api/v1/accounts/:account_id/help_links

Scope: url:GET|/api/v1/accounts/:account_id/help_links

Returns the help links for that account

Returns a HelpLinks object

Get the manually-created courses sub-account for the domain root account AccountsController#manually_created_courses_account

GET /api/v1/manually_created_courses_account

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

List active courses in an account AccountsController#courses_api

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

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

Retrieve a paginated list of courses in this account.

Request Parameters:

Parameter Type Description
with_enrollments boolean

If true, include only courses with at least one enrollment. If false, include only courses with no enrollments. If not present, do not filter on course enrollment status.

enrollment_type[] string

If set, only return courses that have at least one user enrolled in in the course with one of the specified enrollment types.

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

published boolean

If true, include only published courses. If false, exclude published courses. If not present, do not filter on published status.

completed boolean

If true, include only completed courses (these may be in state ‘completed’, or their enrollment term may have ended). If false, exclude completed courses. If not present, do not filter on completed status.

blueprint boolean

If true, include only blueprint courses. If false, exclude them. If not present, do not filter on this basis.

blueprint_associated boolean

If true, include only courses that inherit content from a blueprint course. If false, exclude them. If not present, do not filter on this basis.

public boolean

If true, include only public courses. If false, exclude them. If not present, do not filter on this basis.

by_teachers[] integer

List of User IDs of teachers; if supplied, include only courses taught by one of the referenced users.

by_subaccounts[] integer

List of Account IDs; if supplied, include only courses associated with one of the referenced subaccounts.

hide_enrollmentless_courses boolean

If present, only return courses that have at least one enrollment. Equivalent to ‘with_enrollments=true’; retained for compatibility.

state[] string

If set, only return courses that are in the given state(s). By default, all states but “deleted” are returned.

Allowed values: created, claimed, available, completed, deleted, all

enrollment_term_id integer

If set, only includes courses from the specified term.

search_term string

The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters.

include[] string
  • All explanations can be seen in the Course API index documentation

  • “sections”, “needs_grading_count” and “total_scores” are not valid options at the account level

Allowed values: syllabus_body, term, course_progress, storage_quota_used_mb, total_students, teachers, account_name, concluded, post_manually

sort string

The column to sort results by.

Allowed values: course_status, course_name, sis_course_id, teacher, account_name

order string

The order to sort the given column by.

Allowed values: asc, desc

search_by string

The filter to search by. “course” searches for course names, course codes, and SIS IDs. “teacher” searches for teacher names

Allowed values: course, teacher

starts_before Date

If set, only return courses that start before the value (inclusive) or their enrollment term starts before the value (inclusive) or both the course’s start_at and the enrollment term’s start_at are set to null. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.

ends_after Date

If set, only return courses that end after the value (inclusive) or their enrollment term ends after the value (inclusive) or both the course’s end_at and the enrollment term’s end_at are set to null. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.

homeroom boolean

If set, only return homeroom courses.

Returns a list of Course objects

Update an account AccountsController#update

PUT /api/v1/accounts/:id

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

Update an existing account.

Request Parameters:

Parameter Type Description
account[name] string

Updates the account name

account[sis_account_id] string

Updates the account sis_account_id Must have manage_sis permission and must not be a root_account.

account[default_time_zone] string

The default time zone of the account. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

account[default_storage_quota_mb] integer

The default course storage quota to be used, if not otherwise specified.

account[default_user_storage_quota_mb] integer

The default user storage quota to be used, if not otherwise specified.

account[default_group_storage_quota_mb] integer

The default group storage quota to be used, if not otherwise specified.

account[course_template_id] integer

The ID of a course to be used as a template for all newly created courses. Empty means to inherit the setting from parent account, 0 means to not use a template even if a parent account has one set. The course must be marked as a template.

account[parent_account_id] integer

The ID of a parent account to move the account to. The new parent account must be in the same root account as the original. The hierarchy of sub-accounts will be preserved in the new parent account. The caller must be an administrator in both the original parent account and the new parent account.

account[settings][restrict_student_past_view][value] boolean

Restrict students from viewing courses after end date

account[settings][restrict_student_past_view][locked] boolean

Lock this setting for sub-accounts and courses

account[settings][restrict_student_future_view][value] boolean

Restrict students from viewing courses before start date

account[settings][microsoft_sync_enabled] boolean

Determines whether this account has Microsoft Teams Sync enabled or not.

Note that if you are altering Microsoft Teams sync settings you must enable the Microsoft Group enrollment syncing feature flag. In addition, if you are enabling Microsoft Teams sync, you must also specify a tenant, login attribute, and a remote attribute. Specifying a suffix to use is optional.

account[settings][microsoft_sync_tenant] string

The tenant this account should use when using Microsoft Teams Sync. This should be an Azure Active Directory domain name.

account[settings][microsoft_sync_login_attribute] string

The attribute this account should use to lookup users when using Microsoft Teams Sync. Must be one of “sub”, “email”, “oid”, “preferred_username”, or “integration_id”.

account[settings][microsoft_sync_login_attribute_suffix] string

A suffix that will be appended to the result of the login attribute when associating Canvas users with Microsoft users. Must be under 255 characters and contain no whitespace. This field is optional.

account[settings][microsoft_sync_remote_attribute] string

The Active Directory attribute to use when associating Canvas users with Microsoft users. Must be one of “mail”, “mailNickname”, or “userPrincipalName”.

account[settings][restrict_student_future_view][locked] boolean

Lock this setting for sub-accounts and courses

account[settings][lock_all_announcements][value] boolean

Disable comments on announcements

account[settings][lock_all_announcements][locked] boolean

Lock this setting for sub-accounts and courses

account[settings][usage_rights_required][value] boolean

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

account[settings][usage_rights_required][locked] boolean

Lock this setting for sub-accounts and courses

account[settings][restrict_student_future_listing][value] boolean

Restrict students from viewing future enrollments in course list

account[settings][restrict_student_future_listing][locked] boolean

Lock this setting for sub-accounts and courses

account[settings][conditional_release][value] boolean

Enable or disable individual learning paths for students based on assessment

account[settings][conditional_release][locked] boolean

Lock this setting for sub-accounts and courses

account[settings][password_policy] Hash

Hash of optional password policy configuration parameters for a root account

allow_login_suspension boolean

Allow suspension of user logins upon reaching maximum_login_attempts

require_number_characters boolean

Require the use of number characters when setting up a new password

require_symbol_characters boolean

Require the use of symbol characters when setting up a new password

minimum_character_length integer

Minimum number of characters required for a new password

maximum_login_attempts integer

Maximum number of login attempts before a user is locked out

Required feature option:

Enhance password options
account[settings][enable_as_k5_account][value] boolean

Enable or disable Canvas for Elementary for this account

account[settings][use_classic_font_in_k5][value] boolean

Whether or not the classic font is used on the dashboard. Only applies if enable_as_k5_account is true.

override_sis_stickiness boolean

Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness

account[settings][lock_outcome_proficiency][value] boolean
DEPRECATED

Restrict instructors from changing mastery scale

account[lock_outcome_proficiency][locked] boolean
DEPRECATED

Lock this setting for sub-accounts and courses

account[settings][lock_proficiency_calculation][value] boolean
DEPRECATED

Restrict instructors from changing proficiency calculation method

account[lock_proficiency_calculation][locked] boolean
DEPRECATED

Lock this setting for sub-accounts and courses

account[services] Hash

Give this a set of keys and boolean values to enable or disable services matching the keys

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'account[name]=New account name' \
  -d 'account[default_time_zone]=Mountain Time (US & Canada)' \
  -d 'account[default_storage_quota_mb]=450'
Returns an Account object

Delete a user from the root account AccountsController#remove_user

DELETE /api/v1/accounts/:account_id/users/:user_id

Scope: url:DELETE|/api/v1/accounts/:account_id/users/:user_id

Delete a user record from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts.

WARNING: This API will allow a user to remove themselves from the account. If they do this, they won’t be able to make API calls or log into Canvas at that account.

Example Request:

curl https://<canvas>/api/v1/accounts/3/users/5 \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -X DELETE
Returns an User object

Restore a deleted user from a root account AccountsController#restore_user

PUT /api/v1/accounts/:account_id/users/:user_id/restore

Scope: url:PUT|/api/v1/accounts/:account_id/users/:user_id/restore

Restore a user record along with the most recently deleted pseudonym from a Canvas root account.

Example Request:

curl https://<canvas>/api/v1/accounts/3/users/5/restore \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -X PUT
Returns an User object

Create a new sub-account SubAccountsController#create

POST /api/v1/accounts/:account_id/sub_accounts

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

Add a new sub-account to a given account.

Request Parameters:

Parameter Type Description
account[name] Required string

The name of the new sub-account.

account[sis_account_id] string

The account’s identifier in the Student Information System.

account[default_storage_quota_mb] integer

The default course storage quota to be used, if not otherwise specified.

account[default_user_storage_quota_mb] integer

The default user storage quota to be used, if not otherwise specified.

account[default_group_storage_quota_mb] integer

The default group storage quota to be used, if not otherwise specified.

Returns an Account object

Delete a sub-account SubAccountsController#destroy

DELETE /api/v1/accounts/:account_id/sub_accounts/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/sub_accounts/:id

Cannot delete an account with active courses or active sub_accounts. Cannot delete a root_account

Returns an Account object

Get account Lti::AccountLookupController#show

GET /api/lti/accounts/:account_id

Scope: url:GET|/api/lti/accounts/:account_id

Retrieve information on an individual account, given by local or global ID.

Returns an Account object

Make an account admin AdminsController#create

POST /api/v1/accounts/:account_id/admins

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

Flag an existing user as an admin within the account.

Request Parameters:

Parameter Type Description
user_id Required integer

The id of the user to promote.

role string
DEPRECATED

The user’s admin relationship with the account will be

created with the given role. Defaults to ‘AccountAdmin’.

role_id integer

The user’s admin relationship with the account will be created with the given role. Defaults to the built-in role for ‘AccountAdmin’.

send_confirmation boolean

Send a notification email to the new admin if true. Default is true.

Returns an Admin object

Remove account admin AdminsController#destroy

DELETE /api/v1/accounts/:account_id/admins/:user_id

Scope: url:DELETE|/api/v1/accounts/:account_id/admins/:user_id

Remove the rights associated with an account admin role from a user.

Request Parameters:

Parameter Type Description
role string
DEPRECATED

Account role to remove from the user.

role_id Required integer

The id of the role representing the user’s admin relationship with the account.

Returns an Admin object

List account admins AdminsController#index

GET /api/v1/accounts/:account_id/admins

Scope: url:GET|/api/v1/accounts/:account_id/admins

A paginated list of the admins in the account

Request Parameters:

Parameter Type Description
user_id[] [Integer]

Scope the results to those with user IDs equal to any of the IDs specified here.

Returns a list of Admin objects

List my admin roles AdminsController#self_roles

GET /api/v1/accounts/:account_id/admins/self

Scope: url:GET|/api/v1/accounts/:account_id/admins/self

A paginated list of the current user’s roles in the account. The results are the same as those returned by the List account admins endpoint with user_id set to self, except the “Admins - Add / Remove” permission is not required.

Returns a list of Admin objects

Get department-level participation data

GET /api/v1/accounts/:account_id/analytics/terms/:term_id/activity

Scope: url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/activity

GET /api/v1/accounts/:account_id/analytics/current/activity

Scope: url:GET|/api/v1/accounts/:account_id/analytics/current/activity

GET /api/v1/accounts/:account_id/analytics/completed/activity

Scope: url:GET|/api/v1/accounts/:account_id/analytics/completed/activity

Returns page view hits summed across all courses in the department. Two groupings of these counts are returned; one by day (by_date), the other by category (by_category). The possible categories are announcements, assignments, collaborations, conferences, discussions, files, general, grades, groups, modules, other, pages, and quizzes.

This and the other department-level endpoints have three variations which all return the same style of data but for different subsets of courses. All share the prefix /api/v1/accounts/<account_id>/analytics. The possible suffixes are:

* /current: includes all available courses in the default term
* /completed: includes all concluded courses in the default term
* /terms/<term_id>: includes all available or concluded courses in the
  given term.

Courses not yet offered or which have been deleted are never included.

/current and /completed are intended for use when the account has only one term. /terms/<term_id> is intended for use when the account has multiple terms.

The action follows the suffix.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/current/activity \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/completed/activity \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/terms/<term_id>/activity \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "by_date": {
    "2012-01-24": 1240,
    "2012-01-27": 912,
  },
  "by_category": {
    "announcements": 54,
    "assignments": 256,
    "collaborations": 18,
    "conferences": 26,
    "discussions": 354,
    "files": 132,
    "general": 59,
    "grades": 177,
    "groups": 132,
    "modules": 71,
    "other": 412,
    "pages": 105,
    "quizzes": 356
  },
}

Get department-level grade data

GET /api/v1/accounts/:account_id/analytics/terms/:term_id/grades

Scope: url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/grades

GET /api/v1/accounts/:account_id/analytics/current/grades

Scope: url:GET|/api/v1/accounts/:account_id/analytics/current/grades

GET /api/v1/accounts/:account_id/analytics/completed/grades

Scope: url:GET|/api/v1/accounts/:account_id/analytics/completed/grades

Returns the distribution of grades for students in courses in the department. Each data point is one student’s current grade in one course; if a student is in multiple courses, he contributes one value per course, but if he’s enrolled multiple times in the same course (e.g. a lecture section and a lab section), he only constributes on value for that course.

Grades are binned to the nearest integer score; anomalous grades outside the 0 to 100 range are ignored. The raw counts are returned, not yet normalized by the total count.

Shares the same variations on endpoint as the participation data.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/current/grades \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/completed/grades \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/terms/<term_id>/grades \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "0": 95,
  "1": 1,
  "2": 0,
  "3": 0,
  ...
  "93": 125,
  "94": 110,
  "95": 142,
  "96": 157,
  "97": 116,
  "98": 85,
  "99": 63,
  "100": 190
}

Get department-level statistics

GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics

Scope: url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics

GET /api/v1/accounts/:account_id/analytics/current/statistics

Scope: url:GET|/api/v1/accounts/:account_id/analytics/current/statistics

GET /api/v1/accounts/:account_id/analytics/completed/statistics

Scope: url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics

Returns numeric statistics about the department and term (or filter).

Shares the same variations on endpoint as the participation data.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/current/statistics \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/completed/statistics \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/terms/<term_id>/statistics \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "courses": 27,
  "subaccounts": 3,
  "teachers": 36,
  "students": 418,
  "discussion_topics": 77,
  "media_objects": 219,
  "attachments": 1268,
  "assignments": 290,
}

Get department-level statistics, broken down by subaccount

GET /api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount

Scope: url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics_by_subaccount

GET /api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount

Scope: url:GET|/api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount

GET /api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount

Scope: url:GET|/api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount

Returns numeric statistics about the department subaccounts and term (or filter).

Shares the same variations on endpoint as the participation data.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/current/statistics_by_subaccount \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/completed/statistics_by_subaccount \
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/accounts/<account_id>/analytics/terms/<term_id>/statistics_by_subaccount \
    -H 'Authorization: Bearer <token>'

Example Response:

{"accounts": [
  {
    "name": "some string",
    "id": 188,
    "courses": 27,
    "teachers": 36,
    "students": 418,
    "discussion_topics": 77,
    "media_objects": 219,
    "attachments": 1268,
    "assignments": 290,
  }
]}

Get course-level participation data

GET /api/v1/courses/:course_id/analytics/activity

Scope: url:GET|/api/v1/courses/:course_id/analytics/activity

Returns page view hits and participation numbers grouped by day through the entire history of the course. Page views is returned as a hash, where the hash keys are dates in the format “YYYY-MM-DD”. The page_views result set includes page views broken out by access category. Participations is returned as an array of dates in the format “YYYY-MM-DD”.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/analytics/activity \
    -H 'Authorization: Bearer <token>'

Example Response:

[
  {
    "date": "2012-01-24",
    "participations": 3,
    "views": 10
  }
]

Get course-level assignment data

GET /api/v1/courses/:course_id/analytics/assignments

Scope: url:GET|/api/v1/courses/:course_id/analytics/assignments

Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown, and a breakdown of on-time/late status of homework submissions.

Request Parameters:

Parameter Type Description
async boolean

If async is true, then the course_assignments call can happen asynch- ronously and MAY return a response containing a progress_url key instead of an assignments array. If it does, then it is the caller’s responsibility to poll the API again to see if the progress is complete. If the data is ready (possibly even on the first async call) then it will be passed back normally, as documented in the example response.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/analytics/assignments \
    -H 'Authorization: Bearer <token>'

Example Response:

[
  {
    "assignment_id": 1234,
    "title": "Assignment 1",
    "points_possible": 10,
    "due_at": "2012-01-25T22:00:00-07:00",
    "unlock_at": "2012-01-20T22:00:00-07:00",
    "muted": false,
    "min_score": 2,
    "max_score": 10,
    "median": 7,
    "first_quartile": 4,
    "third_quartile": 8,
    "tardiness_breakdown": {
      "on_time": 0.75,
      "missing": 0.1,
      "late": 0.15
    }
  },
  {
    "assignment_id": 1235,
    "title": "Assignment 2",
    "points_possible": 15,
    "due_at": "2012-01-26T22:00:00-07:00",
    "unlock_at": null,
    "muted": true,
    "min_score": 8,
    "max_score": 8,
    "median": 8,
    "first_quartile": 8,
    "third_quartile": 8,
    "tardiness_breakdown": {
      "on_time": 0.65,
      "missing": 0.12,
      "late": 0.23
      "total": 275
    }
  }
]

Get course-level student summary data

GET /api/v1/courses/:course_id/analytics/student_summaries

Scope: url:GET|/api/v1/courses/:course_id/analytics/student_summaries

Returns a summary of per-user access information for all students in a course. This includes total page views, total participations, and a breakdown of on-time/late status for all homework submissions in the course.

Each student’s summary also includes the maximum number of page views and participations by any student in the course, which may be useful for some visualizations (since determining maximums client side can be tricky with pagination).

Request Parameters:

Parameter Type Description
sort_column string

The order results in which results are returned. Defaults to “name”.

Allowed values: name, name_descending, score, score_descending, participations, participations_descending, page_views, page_views_descending

student_id string

If set, returns only the specified student.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/analytics/student_summaries \
    -H 'Authorization: Bearer <token>'

Example Response:

[
  {
    "id": 2346,
    "page_views": 351,
    "page_views_level": "1"
    "max_page_view": 415,
    "participations": 1,
    "participations_level": "3",
    "max_participations": 10,
    "tardiness_breakdown": {
      "total": 5,
      "on_time": 3,
      "late": 0,
      "missing": 2,
      "floating": 0
    }
  },
  {
    "id": 2345,
    "page_views": 124,
    "participations": 15,
    "tardiness_breakdown": {
      "total": 5,
      "on_time": 1,
      "late": 2,
      "missing": 3,
      "floating": 0
    }
  }
]

Get user-in-a-course-level participation data

GET /api/v1/courses/:course_id/analytics/users/:student_id/activity

Scope: url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity

Returns page view hits grouped by hour, and participation details through the entire history of the course.

‘page_views` are returned as a hash, where the keys are iso8601 dates, bucketed by the hour. `participations` are returned as an array of hashes, sorted oldest to newest.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/analytics/users/<user_id>/activity \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "page_views": {
    "2012-01-24T13:00:00-00:00": 19,
    "2012-01-24T14:00:00-00:00": 13,
    "2012-01-27T09:00:00-00:00": 23
  },
  "participations": [
    {
      "created_at": "2012-01-21T22:00:00-06:00",
      "url": "https://canvas.example.com/path/to/canvas",
    },
    {
      "created_at": "2012-01-27T22:00:00-06:00",
      "url": "https://canvas.example.com/path/to/canvas",
    }
  ]
}

Get user-in-a-course-level assignment data

GET /api/v1/courses/:course_id/analytics/users/:student_id/assignments

Scope: url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/assignments

Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown (including the student’s actual grade), and the basic submission information for the student’s submission if it exists.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/analytics/users/<user_id>/assignments \
    -H 'Authorization: Bearer <token>'

Example Response:

[
  {
    "assignment_id": 1234,
    "title": "Assignment 1",
    "points_possible": 10,
    "due_at": "2012-01-25T22:00:00-07:00",
    "unlock_at": "2012-01-20T22:00:00-07:00",
    "muted": false,
    "min_score": 2,
    "max_score": 10,
    "median": 7,
    "first_quartile": 4,
    "third_quartile": 8,
    "module_ids": [
        1,
        2
    ],
    "submission": {
      "posted_at": "2012-01-23T20:00:00-07:00",
      "submitted_at": "2012-01-22T22:00:00-07:00",
      "score": 10
    }
  },
  {
    "assignment_id": 1235,
    "title": "Assignment 2",
    "points_possible": 15,
    "due_at": "2012-01-26T22:00:00-07:00",
    "unlock_at": null,
    "muted": true,
    "min_score": 8,
    "max_score": 8,
    "median": 8,
    "first_quartile": 8,
    "third_quartile": 8,
    "module_ids": [
        1
    ],
    "submission": {
      "posted_at": null,
      "submitted_at": "2012-01-22T22:00:00-07:00"
    }
  }
]

Get user-in-a-course-level messaging data

GET /api/v1/courses/:course_id/analytics/users/:student_id/communication

Scope: url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/communication

Returns messaging “hits” grouped by day through the entire history of the course. Returns a hash containing the number of instructor-to-student messages, and student-to-instructor messages, where the hash keys are dates in the format “YYYY-MM-DD”. Message hits include Conversation messages and comments on homework submissions.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/analytics/users/<user_id>/communication \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "2012-01-24":{
    "instructorMessages":1,
    "studentMessages":2
  },
  "2012-01-27":{
    "studentMessages":1
  }
}

List external feeds ExternalFeedsController#index

GET /api/v1/courses/:course_id/external_feeds

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

GET /api/v1/groups/:group_id/external_feeds

Scope: url:GET|/api/v1/groups/:group_id/external_feeds

Returns the paginated list of External Feeds this course or group.

Example Request:

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

Create an external feed ExternalFeedsController#create

POST /api/v1/courses/:course_id/external_feeds

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

POST /api/v1/groups/:group_id/external_feeds

Scope: url:POST|/api/v1/groups/:group_id/external_feeds

Create a new external feed for the course or group.

Request Parameters:

Parameter Type Description
url Required string

The url to the external rss or atom feed

header_match boolean

If given, only feed entries that contain this string in their title will be imported

verbosity string

Defaults to “full”

Allowed values: full, truncate, link_only

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/external_feeds \
    -F url='http://example.com/rss.xml' \
    -F header_match='news flash!' \
    -F verbosity='full' \
    -H 'Authorization: Bearer <token>'
Returns an ExternalFeed object

Delete an external feed ExternalFeedsController#destroy

DELETE /api/v1/courses/:course_id/external_feeds/:external_feed_id

Scope: url:DELETE|/api/v1/courses/:course_id/external_feeds/:external_feed_id

DELETE /api/v1/groups/:group_id/external_feeds/:external_feed_id

Scope: url:DELETE|/api/v1/groups/:group_id/external_feeds/:external_feed_id

Deletes the external feed.

Example Request:

curl -X DELETE https://<canvas>/api/v1/courses/<course_id>/external_feeds/<feed_id> \
     -H 'Authorization: Bearer <token>'
Returns an ExternalFeed object

List announcements AnnouncementsApiController#index

GET /api/v1/announcements

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

Returns the paginated list of announcements for the given courses and date range. Note that a context_code field is added to the responses so you can tell which course each announcement belongs to.

Request Parameters:

Parameter Type Description
context_codes[] Required string

List of context_codes to retrieve announcements for (for example, course_123). Only courses are presently supported. The call will fail unless the caller has View Announcements permission in all listed courses.

start_date Date

Only return announcements posted since the start_date (inclusive). Defaults to 14 days ago. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.

end_date Date

Only return announcements posted before the end_date (inclusive). Defaults to 28 days from start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. Announcements scheduled for future posting will only be returned to course administrators.

available_after Date

Only return announcements having locked_at nil or after available_after (exclusive). The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. Effective only for students (who don’t have moderate forum right).

active_only boolean

Only return active announcements that have been published. Applies only to requesting users that have permission to view unpublished items. Defaults to false for users with access to view unpublished items, otherwise true and unmodifiable.

latest_only boolean

Only return the latest announcement for each associated context. The response will include at most one announcement for each specified context in the context_codes[] parameter. Defaults to false.

include array

Optional list of resources to include with the response. May include a string of the name of the resource. Possible values are: “sections”, “sections_user_count” if “sections” is passed, includes the course sections that are associated with the topic, if the topic is specific to certain sections of the course. If “sections_user_count” is passed, then:

(a) If sections were asked for *and* the topic is specific to certain
    course sections sections, includes the number of users in each
    section. (as part of the section json asked for above)
(b) Else, includes at the root level the total number of users in the
    topic's context (group or course) that the topic applies to.

Example Request:

curl https://<canvas>/api/v1/announcements?context_codes[]=course_1&context_codes[]=course_2 \
     -H 'Authorization: Bearer <token>'

Example Response:

[{
  "id": 1,
  "title": "Hear ye",
  "message": "Henceforth, all assignments must be...",
  "posted_at": "2017-01-31T22:00:00Z",
  "delayed_post_at": null,
  "context_code": "course_2",
  ...
}]
Returns a list of DiscussionTopic objects

List scopes ScopesApiController#index

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/accounts/:account_id/scopes

Scope: url:GET|/api/v1/accounts/:account_id/scopes

A list of scopes that can be applied to developer keys and access tokens.

Request Parameters:

Parameter Type Description
group_by string

The attribute to group the scopes by. By default no grouping is done.

Allowed values: resource_name

Returns a list of Scope objects

List appointment groups AppointmentGroupsController#index

GET /api/v1/appointment_groups

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

Retrieve the paginated list of appointment groups that can be reserved or managed by the current user.

Request Parameters:

Parameter Type Description
scope string

Defaults to “reservable”

Allowed values: reservable, manageable

context_codes[] string

Array of context codes used to limit returned results.

include_past_appointments boolean

Defaults to false. If true, includes past appointment groups

include[] string

Array of additional information to include.

“appointments”

calendar event time slots for this appointment group

“child_events”

reservations of those time slots

“participant_count”

number of reservations

“reserved_times”

the event id, start time and end time of reservations the current user has made)

“all_context_codes”

all context codes associated with this appointment group

Allowed values: appointments, child_events, participant_count, reserved_times, all_context_codes

Create an appointment group AppointmentGroupsController#create

POST /api/v1/appointment_groups

Scope: url:POST|/api/v1/appointment_groups

Create and return a new appointment group. If new_appointments are specified, the response will return a new_appointments array (same format as appointments array, see “List appointment groups” action)

Request Parameters:

Parameter Type Description
appointment_group[context_codes][] Required string

Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.

appointment_group[sub_context_codes][] string

Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be “Group” instead of “User”.

appointment_group[title] Required string

Short title for the appointment group.

appointment_group[description] string

Longer text description of the appointment group.

appointment_group[location_name] string

Location name of the appointment group.

appointment_group[location_address] string

Location address.

appointment_group[publish] boolean

Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.

appointment_group[participants_per_appointment] integer

Maximum number of participants that may register for each time slot. Defaults to null (no limit).

appointment_group[min_appointments_per_participant] integer

Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots.

appointment_group[max_appointments_per_participant] integer

Maximum number of time slots a user may register for.

appointment_group[new_appointments][X][] string

Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.

appointment_group[participant_visibility] string
“private”

participants cannot see who has signed up for a particular time slot

“protected”

participants can see who has signed up. Defaults to “private”.

Allowed values: private, protected

appointment_group[allow_observer_signup] boolean

Whether observer users can sign-up for an appointment. Defaults to false.

Example Request:

curl 'https://<canvas>/api/v1/appointment_groups.json' \
     -X POST \
     -F 'appointment_group[context_codes][]=course_123' \
     -F 'appointment_group[sub_context_codes][]=course_section_234' \
     -F 'appointment_group[title]=Final Presentation' \
     -F 'appointment_group[participants_per_appointment]=1' \
     -F 'appointment_group[min_appointments_per_participant]=1' \
     -F 'appointment_group[max_appointments_per_participant]=1' \
     -F 'appointment_group[new_appointments][0][]=2012-07-19T21:00:00Z' \
     -F 'appointment_group[new_appointments][0][]=2012-07-19T22:00:00Z' \
     -F 'appointment_group[new_appointments][1][]=2012-07-19T22:00:00Z' \
     -F 'appointment_group[new_appointments][1][]=2012-07-19T23:00:00Z' \
     -H "Authorization: Bearer <token>"

Get a single appointment group AppointmentGroupsController#show

GET /api/v1/appointment_groups/:id

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

Returns information for a single appointment group

Request Parameters:

Parameter Type Description
include[] string

Array of additional information to include. See include[] argument of “List appointment groups” action.

“child_events”

reservations of time slots time slots

“appointments”

will always be returned

“all_context_codes”

all context codes associated with this appointment group

Allowed values: child_events, appointments, all_context_codes

Update an appointment group AppointmentGroupsController#update

PUT /api/v1/appointment_groups/:id

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

Update and return an appointment group. If new_appointments are specified, the response will return a new_appointments array (same format as appointments array, see “List appointment groups” action).

Request Parameters:

Parameter Type Description
appointment_group[context_codes][] Required string

Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.

appointment_group[sub_context_codes][] string

Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be “Group” instead of “User”.

appointment_group[title] string

Short title for the appointment group.

appointment_group[description] string

Longer text description of the appointment group.

appointment_group[location_name] string

Location name of the appointment group.

appointment_group[location_address] string

Location address.

appointment_group[publish] boolean

Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.

appointment_group[participants_per_appointment] integer

Maximum number of participants that may register for each time slot. Defaults to null (no limit).

appointment_group[min_appointments_per_participant] integer

Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots.

appointment_group[max_appointments_per_participant] integer

Maximum number of time slots a user may register for.

appointment_group[new_appointments][X][] string

Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.

appointment_group[participant_visibility] string
“private”

participants cannot see who has signed up for a particular time slot

“protected”

participants can see who has signed up. Defaults to “private”.

Allowed values: private, protected

appointment_group[allow_observer_signup] boolean

Whether observer users can sign-up for an appointment.

Example Request:

curl 'https://<canvas>/api/v1/appointment_groups/543.json' \
     -X PUT \
     -F 'appointment_group[publish]=1' \
     -H "Authorization: Bearer <token>"

Delete an appointment group AppointmentGroupsController#destroy

DELETE /api/v1/appointment_groups/:id

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

Delete an appointment group (and associated time slots and reservations) and return the deleted group

Request Parameters:

Parameter Type Description
cancel_reason string

Reason for deleting/canceling the appointment group.

Example Request:

curl 'https://<canvas>/api/v1/appointment_groups/543.json' \
     -X DELETE \
     -F 'cancel_reason=El Tigre Chino got fired' \
     -H "Authorization: Bearer <token>"

List user participants AppointmentGroupsController#users

GET /api/v1/appointment_groups/:id/users

Scope: url:GET|/api/v1/appointment_groups/:id/users

A paginated list of users that are (or may be) participating in this appointment group. Refer to the Users API for the response fields. Returns no results for appointment groups with the “Group” participant_type.

Request Parameters:

Parameter Type Description
registration_status string

Limits results to the a given participation status, defaults to “all”

Allowed values: all, registered, registered

List student group participants AppointmentGroupsController#groups

GET /api/v1/appointment_groups/:id/groups

Scope: url:GET|/api/v1/appointment_groups/:id/groups

A paginated list of student groups that are (or may be) participating in this appointment group. Refer to the Groups API for the response fields. Returns no results for appointment groups with the “User” participant_type.

Request Parameters:

Parameter Type Description
registration_status string

Limits results to the a given participation status, defaults to “all”

Allowed values: all, registered, registered

Get next appointment AppointmentGroupsController#next_appointment

GET /api/v1/appointment_groups/next_appointment

Scope: url:GET|/api/v1/appointment_groups/next_appointment

Return the next appointment available to sign up for. The appointment is returned in a one-element array. If no future appointments are available, an empty array is returned.

Request Parameters:

Parameter Type Description
appointment_group_ids[] string

List of ids of appointment groups to search.

Returns a list of CalendarEvent objects

Set extensions for student assignment submissions AssignmentExtensionsController#create

POST /api/v1/courses/:course_id/assignments/:assignment_id/extensions

Scope: url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/extensions

Responses

  • 200 OK if the request was successful

  • 403 Forbidden if you are not allowed to extend assignments for this course

  • 400 Bad Request if any of the extensions are invalid

Request Parameters:

Parameter Type Description
assignment_extensions[][user_id] Required integer

The ID of the user we want to add assignment extensions for.

assignment_extensions[][extra_attempts] Required integer

Number of times the student is allowed to re-take the assignment over the limit.

Example Request:

{
  "assignment_extensions": [{
    "user_id": 3,
    "extra_attempts": 2
  },{
    "user_id": 2,
    "extra_attempts": 2
  }]
}

Example Response:

{
  "assignment_extensions": [AssignmentExtension]
}

List assignment groups AssignmentGroupsController#index

GET /api/v1/courses/:course_id/assignment_groups

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

Returns the paginated list of assignment groups for the current context. The returned groups are sorted by their position field.

Request Parameters:

Parameter Type Description
include[] string

Associations to include with the group. “discussion_topic”, “all_dates”, “can_edit”, “assignment_visibility” & “submission” are only valid if “assignments” is also included. “score_statistics” requires that the “assignments” and “submission” options are included. The “assignment_visibility” option additionally requires that the Differentiated Assignments course feature be turned on. If “observed_users” is passed along with “assignments” and “submission”, submissions for observed users will also be included as an array.

Allowed values: assignments, discussion_topic, all_dates, assignment_visibility, overrides, submission, observed_users, can_edit, score_statistics

assignment_ids[] string

If “assignments” are included, optionally return only assignments having their ID in this array. This argument may also be passed as a comma separated string.

exclude_assignment_submission_types[] string

If “assignments” are included, those with the specified submission types will be excluded from the assignment groups.

Allowed values: online_quiz, discussion_topic, wiki_page, external_tool

override_assignment_dates boolean

Apply assignment overrides for each assignment, defaults to true.

grading_period_id integer

The id of the grading period in which assignment groups are being requested (Requires grading periods to exist.)

scope_assignments_to_student boolean

If true, all assignments returned will apply to the current user in the specified grading period. If assignments apply to other students in the specified grading period, but not the current user, they will not be returned. (Requires the grading_period_id argument and grading periods to exist. In addition, the current user must be a student.)

Returns a list of AssignmentGroup objects

Get an Assignment Group AssignmentGroupsApiController#show

GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id

Scope: url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id

Returns the assignment group with the given id.

Request Parameters:

Parameter Type Description
include[] string

Associations to include with the group. “discussion_topic” and “assignment_visibility” and “submission” are only valid if “assignments” is also included. “score_statistics” is only valid if “submission” and “assignments” are also included. The “assignment_visibility” option additionally requires that the Differentiated Assignments course feature be turned on.

Allowed values: assignments, discussion_topic, assignment_visibility, submission, score_statistics

override_assignment_dates boolean

Apply assignment overrides for each assignment, defaults to true.

grading_period_id integer

The id of the grading period in which assignment groups are being requested (Requires grading periods to exist on the account)

Returns an AssignmentGroup object

Create an Assignment Group AssignmentGroupsApiController#create

POST /api/v1/courses/:course_id/assignment_groups

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

Create a new assignment group for this course.

Request Parameters:

Parameter Type Description
name string

The assignment group’s name

position integer

The position of this assignment group in relation to the other assignment groups

group_weight number

The percent of the total grade that this assignment group represents

sis_source_id string

The sis source id of the Assignment Group

integration_data Object

The integration data of the Assignment Group

Returns an AssignmentGroup object

Edit an Assignment Group AssignmentGroupsApiController#update

PUT /api/v1/courses/:course_id/assignment_groups/:assignment_group_id

Scope: url:PUT|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id

Modify an existing Assignment Group.

Request Parameters:

Parameter Type Description
name string

The assignment group’s name

position integer

The position of this assignment group in relation to the other assignment groups

group_weight number

The percent of the total grade that this assignment group represents

sis_source_id string

The sis source id of the Assignment Group

integration_data Object

The integration data of the Assignment Group

rules string

The grading rules that are applied within this assignment group See the Assignment Group object definition for format

Returns an AssignmentGroup object

Destroy an Assignment Group AssignmentGroupsApiController#destroy

DELETE /api/v1/courses/:course_id/assignment_groups/:assignment_group_id

Scope: url:DELETE|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id

Deletes the assignment group with the given id.

Request Parameters:

Parameter Type Description
move_assignments_to integer

The ID of an active Assignment Group to which the assignments that are currently assigned to the destroyed Assignment Group will be assigned. NOTE: If this argument is not provided, any assignments in this Assignment Group will be deleted.

Returns an AssignmentGroup object

Delete an assignment AssignmentsController#destroy

DELETE /api/v1/courses/:course_id/assignments/:id

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

Delete the given assignment.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/assignments/<assignment_id> \
     -X DELETE \
     -H 'Authorization: Bearer <token>'
Returns an Assignment object

List assignments AssignmentsApiController#index

GET /api/v1/courses/:course_id/assignments

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

GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments

Scope: url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments

Returns the paginated list of assignments for the current course or assignment group.

Request Parameters:

Parameter Type Description
include[] string

Optional information to include with each assignment:

submission

The current user’s current Submission

assignment_visibility

An array of ids of students who can see the assignment

all_dates

An array of AssignmentDate structures, one for each override, and also a base if the assignment has an “Everyone” / “Everyone Else” date

overrides

An array of AssignmentOverride structures

observed_users

An array of submissions for observed users

can_edit

an extra Boolean value will be included with each Assignment (and AssignmentDate if all_dates is supplied) to indicate whether the caller can edit the assignment or date. Moderated grading and closed grading periods may restrict a user’s ability to edit an assignment.

score_statistics

An object containing min, max, and mean score on this assignment. This will not be included for students if there are less than 5 graded assignments or if disabled by the instructor. Only valid if ‘submission’ is also included.

ab_guid

An array of guid strings for academic benchmarks

Allowed values: submission, assignment_visibility, all_dates, overrides, observed_users, can_edit, score_statistics, ab_guid

search_term string

The partial title of the assignments to match and return.

override_assignment_dates boolean

Apply assignment overrides for each assignment, defaults to true.

needs_grading_count_by_section boolean

Split up “needs_grading_count” by sections into the “needs_grading_count_by_section” key, defaults to false

bucket string

If included, only return certain assignments depending on due date and submission status.

Allowed values: past, overdue, undated, ungraded, unsubmitted, upcoming, future

assignment_ids[] string

if set, return only assignments specified

order_by string

Determines the order of the assignments. Defaults to “position”.

Allowed values: position, name, due_at

post_to_sis boolean

Return only assignments that have post_to_sis set or not set.

new_quizzes boolean

Return only New Quizzes assignments

Returns a list of Assignment objects

List assignments for user AssignmentsApiController#user_index

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

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

Returns the paginated list of assignments for the specified user if the current user has rights to view. See List assignments for valid arguments.

Duplicate assignment AssignmentsApiController#duplicate

POST /api/v1/courses/:course_id/assignments/:assignment_id/duplicate

Scope: url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/duplicate

Duplicate an assignment and return a json based on result_type argument.

Request Parameters:

Parameter Type Description
result_type string

Optional information: When the root account has the feature ‘newquizzes_on_quiz_page` enabled and this argument is set to “Quiz” the response will be serialized into a quiz format(quizzes); When this argument isn’t specified the response will be serialized into an assignment format;

Allowed values: Quiz

Example Request:

curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/assignments/123/duplicate

curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/assignments/123/duplicate?result_type=Quiz
Returns an Assignment object

List group members for a student on an assignment AssignmentsApiController#student_group_members

GET /api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members

Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/users/:user_id/group_members

Returns student ids and names for the group.

Example Request:

curl https://<canvas>/api/v1/courses/1/assignments/1/users/1/group_members
Returns a list of BasicUser objects

Get a single assignment AssignmentsApiController#show

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

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

Returns the assignment with the given id.

Request Parameters:

Parameter Type Description
include[] string

Associations to include with the assignment. The “assignment_visibility” option requires that the Differentiated Assignments course feature be turned on. If “observed_users” is passed, submissions for observed users will also be included. For “score_statistics” to be included, the “submission” option must also be set.

Allowed values: submission, assignment_visibility, overrides, observed_users, can_edit, score_statistics, ab_guid

override_assignment_dates boolean

Apply assignment overrides to the assignment, defaults to true.

needs_grading_count_by_section boolean

Split up “needs_grading_count” by sections into the “needs_grading_count_by_section” key, defaults to false

all_dates boolean

All dates associated with the assignment, if applicable

Returns an Assignment object

Create an assignment AssignmentsApiController#create

POST /api/v1/courses/:course_id/assignments

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

Create a new assignment for this course. The assignment is created in the active state.

Request Parameters:

Parameter Type Description
assignment[name] Required string

The assignment name.

assignment[position] integer

The position of this assignment in the group when displaying assignment lists.

assignment[submission_types][] string

List of supported submission types for the assignment. Unless the assignment is allowing online submissions, the array should only have one element.

If not allowing online submissions, your options are:

"online_quiz"
"none"
"on_paper"
"discussion_topic"
"external_tool"

If you are allowing online submissions, you can have one or many allowed submission types:

"online_upload"
"online_text_entry"
"online_url"
"media_recording" (Only valid when the Kaltura plugin is enabled)
"student_annotation"

Allowed values: online_quiz, none, on_paper, discussion_topic, external_tool, online_upload, online_text_entry, online_url, media_recording, student_annotation

assignment[allowed_extensions][] string

Allowed extensions if submission_types includes “online_upload”

Example:

allowed_extensions: ["docx","ppt"]
assignment[turnitin_enabled] boolean

Only applies when the Turnitin plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles Turnitin submissions for the assignment. Will be ignored if Turnitin is not available for the course.

assignment[vericite_enabled] boolean

Only applies when the VeriCite plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles VeriCite submissions for the assignment. Will be ignored if VeriCite is not available for the course.

assignment[turnitin_settings] string

Settings to send along to turnitin. See Assignment object definition for format.

assignment[integration_data] string

Data used for SIS integrations. Requires admin-level token with the “Manage SIS” permission. JSON string required.

assignment[integration_id] string

Unique ID from third party integrations

assignment[peer_reviews] boolean

If submission_types does not include external_tool,discussion_topic, online_quiz, or on_paper, determines whether or not peer reviews will be turned on for the assignment.

assignment[automatic_peer_reviews] boolean

Whether peer reviews will be assigned automatically by Canvas or if teachers must manually assign peer reviews. Does not apply if peer reviews are not enabled.

assignment[notify_of_update] boolean

If true, Canvas will send a notification to students in the class notifying them that the content has changed.

assignment[group_category_id] integer

If present, the assignment will become a group assignment assigned to the group.

assignment[grade_group_students_individually] integer

If this is a group assignment, teachers have the options to grade students individually. If false, Canvas will apply the assignment’s score to each member of the group. If true, the teacher can manually assign scores to each member of the group.

assignment[external_tool_tag_attributes] string

Hash of external tool parameters if submission_types is [“external_tool”]. See Assignment object definition for format.

assignment[points_possible] number

The maximum points possible on the assignment.

assignment[grading_type] string

The strategy used for grading the assignment. The assignment defaults to “points” if this field is omitted.

Allowed values: pass_fail, percent, letter_grade, gpa_scale, points, not_graded

assignment[due_at] DateTime

The day/time the assignment is due. Must be between the lock dates if there are lock dates. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.

assignment[lock_at] DateTime

The day/time the assignment is locked after. Must be after the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.

assignment[unlock_at] DateTime

The day/time the assignment is unlocked. Must be before the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.

assignment[description] string

The assignment’s description, supports HTML.

assignment[assignment_group_id] integer

The assignment group id to put the assignment in. Defaults to the top assignment group in the course.

assignment[assignment_overrides][] AssignmentOverride

List of overrides for the assignment.

assignment[only_visible_to_overrides] boolean

Whether this assignment is only visible to overrides (Only useful if ‘differentiated assignments’ account setting is on)

assignment[published] boolean

Whether this assignment is published. (Only useful if ‘draft state’ account setting is on) Unpublished assignments are not visible to students.

assignment[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. This will update the grading_type for the course to ‘letter_grade’ unless it is already ‘gpa_scale’.

assignment[omit_from_final_grade] boolean

Whether this assignment is counted towards a student’s final grade.

assignment[hide_in_gradebook] boolean

Whether this assignment is shown in the gradebook.

assignment[quiz_lti] boolean

Whether this assignment should use the Quizzes 2 LTI tool. Sets the submission type to ‘external_tool’ and configures the external tool attributes to use the Quizzes 2 LTI tool configured for this course. Has no effect if no Quizzes 2 LTI tool is configured.

assignment[moderated_grading] boolean

Whether this assignment is moderated.

assignment[grader_count] integer

The maximum number of provisional graders who may issue grades for this assignment. Only relevant for moderated assignments. Must be a positive value, and must be set to 1 if the course has fewer than two active instructors. Otherwise, the maximum value is the number of active instructors in the course minus one, or 10 if the course has more than 11 active instructors.

assignment[final_grader_id] integer

The user ID of the grader responsible for choosing final grades for this assignment. Only relevant for moderated assignments.

assignment[grader_comments_visible_to_graders] boolean

Boolean indicating if provisional graders’ comments are visible to other provisional graders. Only relevant for moderated assignments.

assignment[graders_anonymous_to_graders] boolean

Boolean indicating if provisional graders’ identities are hidden from other provisional graders. Only relevant for moderated assignments.

assignment[graders_names_visible_to_final_grader] boolean

Boolean indicating if provisional grader identities are visible to the the final grader. Only relevant for moderated assignments.

assignment[anonymous_grading] boolean

Boolean indicating if the assignment is graded anonymously. If true, graders cannot see student identities.

assignment[allowed_attempts] integer

The number of submission attempts allowed for this assignment. Set to -1 for unlimited attempts.

assignment[annotatable_attachment_id] integer

The Attachment ID of the document being annotated.

Only applies when submission_types includes “student_annotation”.

Returns an Assignment object

Edit an assignment AssignmentsApiController#update

PUT /api/v1/courses/:course_id/assignments/:id

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

Modify an existing assignment.

Request Parameters:

Parameter Type Description
assignment[name] string

The assignment name.

assignment[position] integer

The position of this assignment in the group when displaying assignment lists.

assignment[submission_types][] string

Only applies if the assignment doesn’t have student submissions.

List of supported submission types for the assignment. Unless the assignment is allowing online submissions, the array should only have one element.

If not allowing online submissions, your options are:

"online_quiz"
"none"
"on_paper"
"discussion_topic"
"external_tool"

If you are allowing online submissions, you can have one or many allowed submission types:

"online_upload"
"online_text_entry"
"online_url"
"media_recording" (Only valid when the Kaltura plugin is enabled)
"student_annotation"

Allowed values: online_quiz, none, on_paper, discussion_topic, external_tool, online_upload, online_text_entry, online_url, media_recording, student_annotation

assignment[allowed_extensions][] string

Allowed extensions if submission_types includes “online_upload”

Example:

allowed_extensions: ["docx","ppt"]
assignment[turnitin_enabled] boolean

Only applies when the Turnitin plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles Turnitin submissions for the assignment. Will be ignored if Turnitin is not available for the course.

assignment[vericite_enabled] boolean

Only applies when the VeriCite plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles VeriCite submissions for the assignment. Will be ignored if VeriCite is not available for the course.

assignment[turnitin_settings] string

Settings to send along to turnitin. See Assignment object definition for format.

assignment[sis_assignment_id] string

The sis id of the Assignment

assignment[integration_data] string

Data used for SIS integrations. Requires admin-level token with the “Manage SIS” permission. JSON string required.

assignment[integration_id] string

Unique ID from third party integrations

assignment[peer_reviews] boolean

If submission_types does not include external_tool,discussion_topic, online_quiz, or on_paper, determines whether or not peer reviews will be turned on for the assignment.

assignment[automatic_peer_reviews] boolean

Whether peer reviews will be assigned automatically by Canvas or if teachers must manually assign peer reviews. Does not apply if peer reviews are not enabled.

assignment[notify_of_update] boolean

If true, Canvas will send a notification to students in the class notifying them that the content has changed.

assignment[group_category_id] integer

If present, the assignment will become a group assignment assigned to the group.

assignment[grade_group_students_individually] integer

If this is a group assignment, teachers have the options to grade students individually. If false, Canvas will apply the assignment’s score to each member of the group. If true, the teacher can manually assign scores to each member of the group.

assignment[external_tool_tag_attributes] string

Hash of external tool parameters if submission_types is [“external_tool”]. See Assignment object definition for format.

assignment[points_possible] number

The maximum points possible on the assignment.

assignment[grading_type] string

The strategy used for grading the assignment. The assignment defaults to “points” if this field is omitted.

Allowed values: pass_fail, percent, letter_grade, gpa_scale, points, not_graded

assignment[due_at] DateTime

The day/time the assignment is due. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.

assignment[lock_at] DateTime

The day/time the assignment is locked after. Must be after the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.

assignment[unlock_at] DateTime

The day/time the assignment is unlocked. Must be before the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.

assignment[description] string

The assignment’s description, supports HTML.

assignment[assignment_group_id] integer

The assignment group id to put the assignment in. Defaults to the top assignment group in the course.

assignment[assignment_overrides][] AssignmentOverride

List of overrides for the assignment. If the assignment[assignment_overrides] key is absent, any existing overrides are kept as is. If the assignment[assignment_overrides] key is present, existing overrides are updated or deleted (and new ones created, as necessary) to match the provided list.

assignment[only_visible_to_overrides] boolean

Whether this assignment is only visible to overrides (Only useful if ‘differentiated assignments’ account setting is on)

assignment[published] boolean

Whether this assignment is published. (Only useful if ‘draft state’ account setting is on) Unpublished assignments are not visible to students.

assignment[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. This will update the grading_type for the course to ‘letter_grade’ unless it is already ‘gpa_scale’.

assignment[omit_from_final_grade] boolean

Whether this assignment is counted towards a student’s final grade.

assignment[hide_in_gradebook] boolean

Whether this assignment is shown in the gradebook.

assignment[moderated_grading] boolean

Whether this assignment is moderated.

assignment[grader_count] integer

The maximum number of provisional graders who may issue grades for this assignment. Only relevant for moderated assignments. Must be a positive value, and must be set to 1 if the course has fewer than two active instructors. Otherwise, the maximum value is the number of active instructors in the course minus one, or 10 if the course has more than 11 active instructors.

assignment[final_grader_id] integer

The user ID of the grader responsible for choosing final grades for this assignment. Only relevant for moderated assignments.

assignment[grader_comments_visible_to_graders] boolean

Boolean indicating if provisional graders’ comments are visible to other provisional graders. Only relevant for moderated assignments.

assignment[graders_anonymous_to_graders] boolean

Boolean indicating if provisional graders’ identities are hidden from other provisional graders. Only relevant for moderated assignments.

assignment[graders_names_visible_to_final_grader] boolean

Boolean indicating if provisional grader identities are visible to the the final grader. Only relevant for moderated assignments.

assignment[anonymous_grading] boolean

Boolean indicating if the assignment is graded anonymously. If true, graders cannot see student identities.

assignment[allowed_attempts] integer

The number of submission attempts allowed for this assignment. Set to -1 or null for unlimited attempts.

assignment[annotatable_attachment_id] integer

The Attachment ID of the document being annotated.

Only applies when submission_types includes “student_annotation”.

assignment[force_updated_at] boolean

If true, updated_at will be set even if no changes were made.

assignment[submission_types][] string
[DEPRECATED]
Effective 2021-05-26 (notice given 2021-02-18)

Only applies if the assignment doesn’t have student submissions.

Returns an Assignment object

Bulk update assignment dates AssignmentsApiController#bulk_update

PUT /api/v1/courses/:course_id/assignments/bulk_update

Scope: url:PUT|/api/v1/courses/:course_id/assignments/bulk_update

Update due dates and availability dates for multiple assignments in a course.

Accepts a JSON array of objects containing two keys each: id, the assignment id, and all_dates, an array of AssignmentDate structures containing the base and/or override dates for the assignment, as returned from the List assignments endpoint with include[]=all_dates.

This endpoint cannot create or destroy assignment overrides; any existing assignment overrides that are not referenced in the arguments will be left alone. If an override is given, any dates that are not supplied with it will be defaulted. To clear a date, specify null explicitly.

All referenced assignments will be validated before any are saved. A list of errors will be returned if any provided dates are invalid, and no changes will be saved.

The bulk update is performed in a background job, use the Progress API to check its status.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/assignments/bulk_update' \
     -X PUT \
     --data '[{
           "id": 1,
           "all_dates": [{
             "base": true,
             "due_at": "2020-08-29T23:59:00-06:00"
           }, {
             "id": 2,
             "due_at": "2020-08-30T23:59:00-06:00"
           }]
         }]' \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>"
Returns a Progress object

List assignment overrides AssignmentOverridesController#index

GET /api/v1/courses/:course_id/assignments/:assignment_id/overrides

Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/overrides

Returns the paginated list of overrides for this assignment that target sections/groups/students visible to the current user.

Returns a list of AssignmentOverride objects

Get a single assignment override AssignmentOverridesController#show

GET /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id

Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id

Returns details of the the override with the given id.

Returns an AssignmentOverride object

Redirect to the assignment override for a group AssignmentOverridesController#group_alias

GET /api/v1/groups/:group_id/assignments/:assignment_id/override

Scope: url:GET|/api/v1/groups/:group_id/assignments/:assignment_id/override

Responds with a redirect to the override for the given group, if any (404 otherwise).

Redirect to the assignment override for a section AssignmentOverridesController#section_alias

GET /api/v1/sections/:course_section_id/assignments/:assignment_id/override

Scope: url:GET|/api/v1/sections/:course_section_id/assignments/:assignment_id/override

Responds with a redirect to the override for the given section, if any (404 otherwise).

Create an assignment override AssignmentOverridesController#create

POST /api/v1/courses/:course_id/assignments/:assignment_id/overrides

Scope: url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/overrides

One of student_ids, group_id, or course_section_id must be present. At most one should be present; if multiple are present only the most specific (student_ids first, then group_id, then course_section_id) is used and any others are ignored.

Request Parameters:

Parameter Type Description
assignment_override[student_ids][] integer

The IDs of the override’s target students. If present, the IDs must each identify a user with an active student enrollment in the course that is not already targetted by a different adhoc override.

assignment_override[title] string

The title of the adhoc assignment override. Required if student_ids is present, ignored otherwise (the title is set to the name of the targetted group or section instead).

assignment_override[group_id] integer

The ID of the override’s target group. If present, the following conditions must be met for the override to be successful:

  1. the assignment MUST be a group assignment (a group_category_id is assigned to it)

  2. the ID must identify an active group in the group set the assignment is in

  3. the ID must not be targetted by a different override

See Appendix: Group assignments for more info.

assignment_override[course_section_id] integer

The ID of the override’s target section. If present, must identify an active section of the assignment’s course not already targetted by a different override.

assignment_override[due_at] DateTime

The day/time the overridden assignment is due. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect due date. May be present but null to indicate the override removes any previous due date.

assignment_override[unlock_at] DateTime

The day/time the overridden assignment becomes unlocked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the unlock date. May be present but null to indicate the override removes any previous unlock date.

assignment_override[lock_at] DateTime

The day/time the overridden assignment becomes locked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the lock date. May be present but null to indicate the override removes any previous lock date.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/assignments/2/overrides.json' \
     -X POST \
     -F 'assignment_override[student_ids][]=8' \
     -F 'assignment_override[title]=Fred Flinstone' \
     -F 'assignment_override[due_at]=2012-10-08T21:00:00Z' \
     -H "Authorization: Bearer <token>"
Returns an AssignmentOverride object

Update an assignment override AssignmentOverridesController#update

PUT /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id

Scope: url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id

All current overridden values must be supplied if they are to be retained; e.g. if due_at was overridden, but this PUT omits a value for due_at, due_at will no longer be overridden. If the override is adhoc and student_ids is not supplied, the target override set is unchanged. Target override sets cannot be changed for group or section overrides.

Request Parameters:

Parameter Type Description
assignment_override[student_ids][] integer

The IDs of the override’s target students. If present, the IDs must each identify a user with an active student enrollment in the course that is not already targetted by a different adhoc override. Ignored unless the override being updated is adhoc.

assignment_override[title] string

The title of an adhoc assignment override. Ignored unless the override being updated is adhoc.

assignment_override[due_at] DateTime

The day/time the overridden assignment is due. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect due date. May be present but null to indicate the override removes any previous due date.

assignment_override[unlock_at] DateTime

The day/time the overridden assignment becomes unlocked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the unlock date. May be present but null to indicate the override removes any previous unlock date.

assignment_override[lock_at] DateTime

The day/time the overridden assignment becomes locked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the lock date. May be present but null to indicate the override removes any previous lock date.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/assignments/2/overrides/3.json' \
     -X PUT \
     -F 'assignment_override[title]=Fred Flinstone' \
     -F 'assignment_override[due_at]=2012-10-08T21:00:00Z' \
     -H "Authorization: Bearer <token>"
Returns an AssignmentOverride object

Delete an assignment override AssignmentOverridesController#destroy

DELETE /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id

Scope: url:DELETE|/api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id

Deletes an override and returns its former details.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/assignments/2/overrides/3.json' \
     -X DELETE \
     -H "Authorization: Bearer <token>"
Returns an AssignmentOverride object

Batch retrieve overrides in a course AssignmentOverridesController#batch_retrieve

GET /api/v1/courses/:course_id/assignments/overrides

Scope: url:GET|/api/v1/courses/:course_id/assignments/overrides

Returns a list of specified overrides in this course, providing they target sections/groups/students visible to the current user. Returns null elements in the list for requests that were not found.

Request Parameters:

Parameter Type Description
assignment_overrides[][id] Required string

Ids of overrides to retrieve

assignment_overrides[][assignment_id] Required string

Ids of assignments for each override

Example Request:

curl 'https://<canvas>/api/v1/courses/12/assignments/overrides.json?assignment_overrides[][id]=109&assignment_overrides[][assignment_id]=122&assignment_overrides[][id]=99&assignment_overrides[][assignment_id]=111' \
     -H "Authorization: Bearer <token>"
Returns a list of AssignmentOverride objects

Batch create overrides in a course AssignmentOverridesController#batch_create

POST /api/v1/courses/:course_id/assignments/overrides

Scope: url:POST|/api/v1/courses/:course_id/assignments/overrides

Creates the specified overrides for each assignment. Handles creation in a transaction, so all records are created or none are.

One of student_ids, group_id, or course_section_id must be present. At most one should be present; if multiple are present only the most specific (student_ids first, then group_id, then course_section_id) is used and any others are ignored.

Errors are reported in an errors attribute, an array of errors corresponding to inputs. Global errors will be reported as a single element errors array

Request Parameters:

Parameter Type Description
assignment_overrides[] Required AssignmentOverride

Attributes for the new assignment overrides. See Create an assignment override for available attributes

Example Request:

curl "https://<canvas>/api/v1/courses/12/assignments/overrides.json" \
     -X POST \
     -F "assignment_overrides[][assignment_id]=109" \
     -F 'assignment_overrides[][student_ids][]=8' \
     -F "assignment_overrides[][title]=foo" \
     -F "assignment_overrides[][assignment_id]=13" \
     -F "assignment_overrides[][course_section_id]=200" \
     -F "assignment_overrides[][due_at]=2012-10-08T21:00:00Z" \
     -H "Authorization: Bearer <token>"
Returns a list of AssignmentOverride objects

Batch update overrides in a course AssignmentOverridesController#batch_update

PUT /api/v1/courses/:course_id/assignments/overrides

Scope: url:PUT|/api/v1/courses/:course_id/assignments/overrides

Updates a list of specified overrides for each assignment. Handles overrides in a transaction, so either all updates are applied or none. See Update an assignment override for available attributes.

All current overridden values must be supplied if they are to be retained; e.g. if due_at was overridden, but this PUT omits a value for due_at, due_at will no longer be overridden. If the override is adhoc and student_ids is not supplied, the target override set is unchanged. Target override sets cannot be changed for group or section overrides.

Errors are reported in an errors attribute, an array of errors corresponding to inputs. Global errors will be reported as a single element errors array

Request Parameters:

Parameter Type Description
assignment_overrides[] Required AssignmentOverride

Attributes for the updated overrides.

Example Request:

curl "https://<canvas>/api/v1/courses/12/assignments/overrides.json" \
     -X PUT \
     -F "assignment_overrides[][id]=122" \
     -F "assignment_overrides[][assignment_id]=109" \
     -F "assignment_overrides[][title]=foo" \
     -F "assignment_overrides[][id]=993" \
     -F "assignment_overrides[][assignment_id]=13" \
     -F "assignment_overrides[][due_at]=2012-10-08T21:00:00Z" \
     -H "Authorization: Bearer <token>"
Returns a list of AssignmentOverride objects

List authentication providers AuthenticationProvidersController#index

GET /api/v1/accounts/:account_id/authentication_providers

Scope: url:GET|/api/v1/accounts/:account_id/authentication_providers

Returns a paginated list of authentication providers

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers' \
     -H 'Authorization: Bearer <token>'
Returns a list of AuthenticationProvider objects

Get authentication provider AuthenticationProvidersController#show

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

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

Get the specified authentication provider

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
     -H 'Authorization: Bearer <token>'
Returns an AuthenticationProvider object

Update authentication provider AuthenticationProvidersController#update

PUT /api/v1/accounts/:account_id/authentication_providers/:id

Scope: url:PUT|/api/v1/accounts/:account_id/authentication_providers/:id

Update an authentication provider using the same options as the create endpoint. You can not update an existing provider to a new authentication type.

Example Request:

# update SAML config
curl -X PUT 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
     -F 'idp_entity_id=<new_idp_entity_id>' \
     -F 'log_in_url=<new_url>' \
     -H 'Authorization: Bearer <token>'
Returns an AuthenticationProvider object

Delete authentication provider AuthenticationProvidersController#destroy

DELETE /api/v1/accounts/:account_id/authentication_providers/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/authentication_providers/:id

Delete the config

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
     -H 'Authorization: Bearer <token>'

Restore a deleted authentication provider AuthenticationProvidersController#restore

PUT /api/v1/accounts/:account_id/authentication_providers/:id/restore

Scope: url:PUT|/api/v1/accounts/:account_id/authentication_providers/:id/restore

Restore an authentication provider back to active that was previously deleted. Only available to admins who can manage_account_settings for given root account.

Example Request:

curl -X PUT 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>/restore' \
     -H 'Authorization: Bearer <token>'
Returns an AuthenticationProvider object

show account auth settings AuthenticationProvidersController#show_sso_settings

GET /api/v1/accounts/:account_id/sso_settings

Scope: url:GET|/api/v1/accounts/:account_id/sso_settings

The way to get the current state of each account level setting that’s relevant to Single Sign On configuration

You can list the current state of each setting with “update_sso_settings”

Example Request:

curl -XGET 'https://<canvas>/api/v1/accounts/<account_id>/sso_settings' \
     -H 'Authorization: Bearer <token>'
Returns a SSOSettings object

update account auth settings AuthenticationProvidersController#update_sso_settings

PUT /api/v1/accounts/:account_id/sso_settings

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

For various cases of mixed SSO configurations, you may need to set some configuration at the account level to handle the particulars of your setup.

This endpoint accepts a PUT request to set several possible account settings. All setting are optional on each request, any that are not provided at all are simply retained as is. Any that provide the key but a null-ish value (blank string, null, undefined) will be UN-set.

You can list the current state of each setting with “show_sso_settings”

Example Request:

curl -XPUT 'https://<canvas>/api/v1/accounts/<account_id>/sso_settings' \
     -F 'sso_settings[auth_discovery_url]=<new_url>' \
     -F 'sso_settings[change_password_url]=<new_url>' \
     -F 'sso_settings[login_handle_name]=<new_handle>' \
     -H 'Authorization: Bearer <token>'
Returns a SSOSettings object

Query by login. AuthenticationAuditApiController#for_login

GET /api/v1/audit/authentication/logins/:login_id

Scope: url:GET|/api/v1/audit/authentication/logins/:login_id

List authentication events for a given login.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events. Events are stored for one year.

end_time DateTime

The end of the time range from which you want events.

Query by account. AuthenticationAuditApiController#for_account

GET /api/v1/audit/authentication/accounts/:account_id

Scope: url:GET|/api/v1/audit/authentication/accounts/:account_id

List authentication events for a given account.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events. Events are stored for one year.

end_time DateTime

The end of the time range from which you want events.

Query by user. AuthenticationAuditApiController#for_user

GET /api/v1/audit/authentication/users/:user_id

Scope: url:GET|/api/v1/audit/authentication/users/:user_id

List authentication events for a given user.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events. Events are stored for one year.

end_time DateTime

The end of the time range from which you want events.

List blackout dates BlackoutDatesController#index

GET /api/v1/courses/:course_id/blackout_dates

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

GET /api/v1/accounts/:account_id/blackout_dates

Scope: url:GET|/api/v1/accounts/:account_id/blackout_dates

Returns the list of blackout dates for the current context.

Returns a list of BlackoutDate objects

Get a single blackout date BlackoutDatesController#show

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

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

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

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

Returns the blackout date with the given id.

Returns a BlackoutDate object

New Blackout Date BlackoutDatesController#new

GET /api/v1/courses/:course_id/blackout_dates/new

Scope: url:GET|/api/v1/courses/:course_id/blackout_dates/new

GET /api/v1/accounts/:account_id/blackout_dates/new

Scope: url:GET|/api/v1/accounts/:account_id/blackout_dates/new

Initialize an unsaved Blackout Date for the given context.

Returns a BlackoutDate object

Create Blackout Date BlackoutDatesController#create

POST /api/v1/courses/:course_id/blackout_dates

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

POST /api/v1/accounts/:account_id/blackout_dates

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

Create a blackout date for the given context.

Request Parameters:

Parameter Type Description
start_date Date

The start date of the blackout date.

end_date Date

The end date of the blackout date.

event_title string

The title of the blackout date.

Returns a BlackoutDate object

Update Blackout Date BlackoutDatesController#update

PUT /api/v1/courses/:course_id/blackout_dates/:id

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

PUT /api/v1/accounts/:account_id/blackout_dates/:id

Scope: url:PUT|/api/v1/accounts/:account_id/blackout_dates/:id

Update a blackout date for the given context.

Request Parameters:

Parameter Type Description
start_date Date

The start date of the blackout date.

end_date Date

The end date of the blackout date.

event_title string

The title of the blackout date.

Returns a BlackoutDate object

Delete Blackout Date BlackoutDatesController#destroy

DELETE /api/v1/courses/:course_id/blackout_dates/:id

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

DELETE /api/v1/accounts/:account_id/blackout_dates/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/blackout_dates/:id

Delete a blackout date for the given context.

Returns a BlackoutDate object

Update a list of Blackout Dates BlackoutDatesController#bulk_update

PUT /api/v1/courses/:course_id/blackout_dates

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

Create, update, and delete blackout dates to sync the db with the incoming data.

Request Parameters:

Parameter Type Description
blackout_dates: string
blackout_date, …

An object containing the array of BlackoutDates we want to exist after this operation. For array entries, if it has an id it will be updated, if not created, and if an existing BlackoutDate id is missing from the array, it will be deleted.

List block templates BlockEditorTemplatesApiController#index

GET /api/v1/courses/:course_id/block_editor_templates

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

A list of the block templates available to the current user.

Request Parameters:

Parameter Type Description
sort string

Sort results by this field.

Allowed values: name, created_at, updated_at

order string

The sorting order. Defaults to ‘asc’.

Allowed values: asc, desc

drafts boolean

If true, include draft templates. If false or omitted only published templates will be returned.

type[] string

What type of templates should be returned.

Allowed values: page, section, block

include[] string

no description

Allowed values: node_tree, thumbnail

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/123/block_editor_templates?sort=name&order=asc&drafts=true
Returns a list of BlockEditorTemplate objects

Get blueprint information MasterCourses::MasterTemplatesController#show

GET /api/v1/courses/:course_id/blueprint_templates/:template_id

Scope: url:GET|/api/v1/courses/:course_id/blueprint_templates/:template_id

Using ‘default’ as the template_id should suffice for the current implmentation (as there should be only one template per course). However, using specific template ids may become necessary in the future

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a BlueprintTemplate object

Get associated course information MasterCourses::MasterTemplatesController#associated_courses

GET /api/v1/courses/:course_id/blueprint_templates/:template_id/associated_courses

Scope: url:GET|/api/v1/courses/:course_id/blueprint_templates/:template_id/associated_courses

Returns a list of courses that are configured to receive updates from this blueprint

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/associated_courses \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a list of Course objects

Update associated courses MasterCourses::MasterTemplatesController#update_associations

PUT /api/v1/courses/:course_id/blueprint_templates/:template_id/update_associations

Scope: url:PUT|/api/v1/courses/:course_id/blueprint_templates/:template_id/update_associations

Send a list of course ids to add or remove new associations for the template. Cannot add courses that do not belong to the blueprint course’s account. Also cannot add other blueprint courses or courses that already have an association with another blueprint course.

After associating new courses, start a sync to populate their contents from the blueprint.

Request Parameters:

Parameter Type Description
course_ids_to_add Array

Courses to add as associated courses

course_ids_to_remove Array

Courses to remove as associated courses

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/update_associations \
-X PUT \
-H 'Authorization: Bearer <token>' \
-d 'course_ids_to_add[]=1' \
-d 'course_ids_to_remove[]=2' \

Begin a migration to push to associated courses MasterCourses::MasterTemplatesController#queue_migration

POST /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations

Scope: url:POST|/api/v1/courses/:course_id/blueprint_templates/:template_id/migrations

Begins a migration to push recently updated content to all associated courses. Only one migration can be running at a time.

Request Parameters:

Parameter Type Description
comment string

An optional comment to be included in the sync history.

send_notification boolean

Send a notification to the calling user when the sync completes.

copy_settings boolean

Whether course settings should be copied over to associated courses. Defaults to true for newly associated courses.

send_item_notifications boolean

By default, new-item notifications are suppressed in blueprint syncs. If this option is set, teachers and students may receive notifications for items such as announcements and assignments that are created in associated courses (subject to the usual notification settings). This option requires the Blueprint Item Notifications feature to be enabled.

publish_after_initial_sync boolean

If set, newly associated courses will be automatically published after the sync completes

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/migrations \
-X POST \
-F 'comment=Fixed spelling in question 3 of midterm exam' \
-F 'send_notification=true' \
-H 'Authorization: Bearer <token>'
Returns a BlueprintMigration object

Set or remove restrictions on a blueprint course object MasterCourses::MasterTemplatesController#restrict_item

PUT /api/v1/courses/:course_id/blueprint_templates/:template_id/restrict_item

Scope: url:PUT|/api/v1/courses/:course_id/blueprint_templates/:template_id/restrict_item

If a blueprint course object is restricted, editing will be limited for copies in associated courses.

Request Parameters:

Parameter Type Description
content_type string
String, “assignment”|“attachment”|“discussion_topic”|“external_tool”|“lti-quiz”|“quiz”|“wiki_page”

The type of the object.

content_id integer

The ID of the object.

restricted boolean

Whether to apply restrictions.

restrictions BlueprintRestriction

(Optional) If the object is restricted, this specifies a set of restrictions. If not specified, the course-level restrictions will be used. See Course API update documentation

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/restrict_item \
-X PUT \
-H 'Authorization: Bearer <token>' \
-d 'content_type=assignment' \
-d 'content_id=2' \
-d 'restricted=true'

Get unsynced changes MasterCourses::MasterTemplatesController#unsynced_changes

GET /api/v1/courses/:course_id/blueprint_templates/:template_id/unsynced_changes

Scope: url:GET|/api/v1/courses/:course_id/blueprint_templates/:template_id/unsynced_changes

Retrieve a list of learning objects that have changed since the last blueprint sync operation. If no syncs have been completed, a ChangeRecord with a change_type of initial_sync is returned.

Returns a list of ChangeRecord objects

List blueprint migrations MasterCourses::MasterTemplatesController#migrations_index

GET /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations

Scope: url:GET|/api/v1/courses/:course_id/blueprint_templates/:template_id/migrations

Shows a paginated list of migrations for the template, starting with the most recent. This endpoint can be called on a blueprint course. See also the associated course side.

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/migrations \
-H 'Authorization: Bearer <token>'
Returns a list of BlueprintMigration objects

Show a blueprint migration MasterCourses::MasterTemplatesController#migrations_show

GET /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations/:id

Scope: url:GET|/api/v1/courses/:course_id/blueprint_templates/:template_id/migrations/:id

Shows the status of a migration. This endpoint can be called on a blueprint course. See also the associated course side.

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/migrations/:id \
-H 'Authorization: Bearer <token>'
Returns a BlueprintMigration object

Get migration details MasterCourses::MasterTemplatesController#migration_details

GET /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations/:id/details

Scope: url:GET|/api/v1/courses/:course_id/blueprint_templates/:template_id/migrations/:id/details

Show the changes that were propagated in a blueprint migration. This endpoint can be called on a blueprint course. See also the associated course side.

Example Request:

curl https://<canvas>/api/v1/courses/1/blueprint_templates/default/migrations/2/details \
-H 'Authorization: Bearer <token>'
Returns a list of ChangeRecord objects

List blueprint subscriptions MasterCourses::MasterTemplatesController#subscriptions_index

GET /api/v1/courses/:course_id/blueprint_subscriptions

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

Returns a list of blueprint subscriptions for the given course. (Currently a course may have no more than one.)

Example Request:

curl https://<canvas>/api/v1/courses/2/blueprint_subscriptions \
-H 'Authorization: Bearer <token>'
Returns a list of BlueprintSubscription objects

List blueprint imports MasterCourses::MasterTemplatesController#imports_index

GET /api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations

Scope: url:GET|/api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations

Shows a paginated list of migrations imported into a course associated with a blueprint, starting with the most recent. See also the blueprint course side.

Use ‘default’ as the subscription_id to use the currently active blueprint subscription.

Example Request:

curl https://<canvas>/api/v1/courses/2/blueprint_subscriptions/default/migrations \
-H 'Authorization: Bearer <token>'
Returns a list of BlueprintMigration objects

Show a blueprint import MasterCourses::MasterTemplatesController#imports_show

GET /api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations/:id

Scope: url:GET|/api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations/:id

Shows the status of an import into a course associated with a blueprint. See also the blueprint course side.

Example Request:

curl https://<canvas>/api/v1/courses/2/blueprint_subscriptions/default/migrations/:id \
-H 'Authorization: Bearer <token>'
Returns a BlueprintMigration object

Get import details MasterCourses::MasterTemplatesController#import_details

GET /api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations/:id/details

Scope: url:GET|/api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations/:id/details

Show the changes that were propagated to a course associated with a blueprint. See also the blueprint course side.

Example Request:

curl https://<canvas>/api/v1/courses/2/blueprint_subscriptions/default/7/details \
-H 'Authorization: Bearer <token>'
Returns a list of ChangeRecord objects

List bookmarks Bookmarks::BookmarksController#index

GET /api/v1/users/self/bookmarks

Scope: url:GET|/api/v1/users/self/bookmarks

Returns the paginated list of bookmarks.

Example Request:

curl 'https://<canvas>/api/v1/users/self/bookmarks' \
     -H 'Authorization: Bearer <token>'
Returns a list of Bookmark objects

Create bookmark Bookmarks::BookmarksController#create

POST /api/v1/users/self/bookmarks

Scope: url:POST|/api/v1/users/self/bookmarks

Creates a bookmark.

Request Parameters:

Parameter Type Description
name string

The name of the bookmark

url string

The url of the bookmark

position integer

The position of the bookmark. Defaults to the bottom.

data string

The data associated with the bookmark

Example Request:

curl 'https://<canvas>/api/v1/users/self/bookmarks' \
     -F 'name=Biology 101' \
     -F 'url=/courses/1' \
     -H 'Authorization: Bearer <token>'
Returns a Bookmark object

Get bookmark Bookmarks::BookmarksController#show

GET /api/v1/users/self/bookmarks/:id

Scope: url:GET|/api/v1/users/self/bookmarks/:id

Returns the details for a bookmark.

Example Request:

curl 'https://<canvas>/api/v1/users/self/bookmarks/1' \
     -H 'Authorization: Bearer <token>'
Returns a Bookmark object

Update bookmark Bookmarks::BookmarksController#update

PUT /api/v1/users/self/bookmarks/:id

Scope: url:PUT|/api/v1/users/self/bookmarks/:id

Updates a bookmark

Request Parameters:

Parameter Type Description
name string

The name of the bookmark

url string

The url of the bookmark

position integer

The position of the bookmark. Defaults to the bottom.

data string

The data associated with the bookmark

Example Request:

curl -X PUT 'https://<canvas>/api/v1/users/self/bookmarks/1' \
     -F 'name=Biology 101' \
     -F 'url=/courses/1' \
     -H 'Authorization: Bearer <token>'
Returns a Folder object

Delete bookmark Bookmarks::BookmarksController#destroy

DELETE /api/v1/users/self/bookmarks/:id

Scope: url:DELETE|/api/v1/users/self/bookmarks/:id

Deletes a bookmark

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/users/self/bookmarks/1' \
     -H 'Authorization: Bearer <token>'

Get the brand config variables that should be used for this domain BrandConfigsApiController#show

GET /api/v1/brand_variables

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

Will redirect to a static json file that has all of the brand variables used by this account. Even though this is a redirect, do not store the redirected url since if the account makes any changes it will redirect to a new url. Needs no authentication.

Example Request:

curl 'https://<canvas>/api/v1/brand_variables'

List calendar events CalendarEventsApiController#index

GET /api/v1/calendar_events

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

Retrieve the paginated list of calendar events or assignments for the current user

Request Parameters:

Parameter Type Description
type string

Defaults to “event”

Allowed values: event, assignment, sub_assignment

start_date Date

Only return events since the start_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.

end_date Date

Only return events before the end_date (inclusive). Defaults to start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end_date is the same as start_date, then only events on that day are returned.

undated boolean

Defaults to false (dated events only). If true, only return undated events and ignore start_date and end_date.

all_events boolean

Defaults to false (uses start_date, end_date, and undated criteria). If true, all events are returned, ignoring start_date, end_date, and undated criteria.

context_codes[] string

List of context codes of courses, groups, users, or accounts whose events you want to see. If not specified, defaults to the current user (i.e personal calendar, no course/group events). Limited to 10 context codes, additional ones are ignored. The format of this field is the context type, followed by an underscore, followed by the context id. For example: course_42

excludes[] Array

Array of attributes to exclude. Possible values are “description”, “child_events” and “assignment”

includes[] Array

Array of optional attributes to include. Possible values are “web_conference” and “series_natural_language”

important_dates boolean

Defaults to false. If true, only events with important dates set to true will be returned.

blackout_date boolean

Defaults to false. If true, only events with blackout date set to true will be returned.

Returns a list of CalendarEvent objects

List calendar events for a user CalendarEventsApiController#user_index

GET /api/v1/users/:user_id/calendar_events

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

Retrieve the paginated list of calendar events or assignments for the specified user. To view calendar events for a user other than yourself, you must either be an observer of that user or an administrator.

Request Parameters:

Parameter Type Description
type string

Defaults to “event”

Allowed values: event, assignment

start_date Date

Only return events since the start_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.

end_date Date

Only return events before the end_date (inclusive). Defaults to start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end_date is the same as start_date, then only events on that day are returned.

undated boolean

Defaults to false (dated events only). If true, only return undated events and ignore start_date and end_date.

all_events boolean

Defaults to false (uses start_date, end_date, and undated criteria). If true, all events are returned, ignoring start_date, end_date, and undated criteria.

context_codes[] string

List of context codes of courses, groups, users, or accounts whose events you want to see. If not specified, defaults to the current user (i.e personal calendar, no course/group events). Limited to 10 context codes, additional ones are ignored. The format of this field is the context type, followed by an underscore, followed by the context id. For example: course_42

excludes[] Array

Array of attributes to exclude. Possible values are “description”, “child_events” and “assignment”

submission_types[] Array

When type is “assignment”, specifies the allowable submission types for returned assignments. Ignored if type is not “assignment” or if exclude_submission_types is provided.

exclude_submission_types[] Array

When type is “assignment”, specifies the submission types to be excluded from the returned assignments. Ignored if type is not “assignment”.

includes[] Array

Array of optional attributes to include. Possible values are “web_conference” and “series_natural_language”

important_dates boolean

Defaults to false If true, only events with important dates set to true will be returned.

blackout_date boolean

Defaults to false If true, only events with blackout date set to true will be returned.

Returns a list of CalendarEvent objects

Create a calendar event CalendarEventsApiController#create

POST /api/v1/calendar_events

Scope: url:POST|/api/v1/calendar_events

Create and return a new calendar event

Request Parameters:

Parameter Type Description
calendar_event[context_code] Required string

Context code of the course, group, user, or account whose calendar this event should be added to.

calendar_event[title] string

Short title for the calendar event.

calendar_event[description] string

Longer HTML description of the event.

calendar_event[start_at] DateTime

Start date/time of the event.

calendar_event[end_at] DateTime

End date/time of the event.

calendar_event[location_name] string

Location name of the event.

calendar_event[location_address] string

Location address

calendar_event[time_zone_edited] string

Time zone of the user editing the event. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

calendar_event[all_day] boolean

When true event is considered to span the whole day and times are ignored.

calendar_event[child_event_data][X][start_at] DateTime

Section-level start time(s) if this is a course event. X can be any identifier, provided that it is consistent across the start_at, end_at and context_code

calendar_event[child_event_data][X][end_at] DateTime

Section-level end time(s) if this is a course event.

calendar_event[child_event_data][X][context_code] string

Context code(s) corresponding to the section-level start and end time(s).

calendar_event[duplicate][count] number

Number of times to copy/duplicate the event. Count cannot exceed 200.

calendar_event[duplicate][interval] number

Defaults to 1 if duplicate ‘count` is set. The interval between the duplicated events.

calendar_event[duplicate][frequency] string

Defaults to “weekly”. The frequency at which to duplicate the event

Allowed values: daily, weekly, monthly

calendar_event[duplicate][append_iterator] boolean

Defaults to false. If set to ‘true`, an increasing counter number will be appended to the event title when the event is duplicated. (e.g. Event 1, Event 2, Event 3, etc)

calendar_event[rrule] string

The recurrence rule to create a series of recurring events. Its value is the iCalendar RRULE defining how the event repeats. Unending series not supported.

calendar_event[blackout_date] boolean

If the blackout_date is true, this event represents a holiday or some other special day that does not count in course pacing.

Example Request:

curl 'https://<canvas>/api/v1/calendar_events.json' \
     -X POST \
     -F 'calendar_event[context_code]=course_123' \
     -F 'calendar_event[title]=Paintball Fight!' \
     -F 'calendar_event[start_at]=2012-07-19T21:00:00Z' \
     -F 'calendar_event[end_at]=2012-07-19T22:00:00Z' \
     -H "Authorization: Bearer <token>"

Get a single calendar event or assignment CalendarEventsApiController#show

GET /api/v1/calendar_events/:id

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

Reserve a time slot CalendarEventsApiController#reserve

POST /api/v1/calendar_events/:id/reservations

Scope: url:POST|/api/v1/calendar_events/:id/reservations

POST /api/v1/calendar_events/:id/reservations/:participant_id

Scope: url:POST|/api/v1/calendar_events/:id/reservations/:participant_id

Reserves a particular time slot and return the new reservation

Request Parameters:

Parameter Type Description
participant_id string

User or group id for whom you are making the reservation (depends on the participant type). Defaults to the current user (or user’s candidate group).

comments string

Comments to associate with this reservation

cancel_existing boolean

Defaults to false. If true, cancel any previous reservation(s) for this participant and appointment group.

Example Request:

curl 'https://<canvas>/api/v1/calendar_events/345/reservations.json' \
     -X POST \
     -F 'cancel_existing=true' \
     -H "Authorization: Bearer <token>"

Update a calendar event CalendarEventsApiController#update

PUT /api/v1/calendar_events/:id

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

Update and return a calendar event

Request Parameters:

Parameter Type Description
calendar_event[context_code] string

Context code of the course, group, user, or account to move this event to. Scheduler appointments and events with section-specific times cannot be moved between calendars.

calendar_event[title] string

Short title for the calendar event.

calendar_event[description] string

Longer HTML description of the event.

calendar_event[start_at] DateTime

Start date/time of the event.

calendar_event[end_at] DateTime

End date/time of the event.

calendar_event[location_name] string

Location name of the event.

calendar_event[location_address] string

Location address

calendar_event[time_zone_edited] string

Time zone of the user editing the event. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

calendar_event[all_day] boolean

When true event is considered to span the whole day and times are ignored.

calendar_event[child_event_data][X][start_at] DateTime

Section-level start time(s) if this is a course event. X can be any identifier, provided that it is consistent across the start_at, end_at and context_code

calendar_event[child_event_data][X][end_at] DateTime

Section-level end time(s) if this is a course event.

calendar_event[child_event_data][X][context_code] string

Context code(s) corresponding to the section-level start and end time(s).

calendar_event[rrule] string

Valid if the event whose ID is in the URL is part of a series. This defines the shape of the recurring event series after it’s updated. Its value is the iCalendar RRULE. Unending series are not supported.

which string

Valid if the event whose ID is in the URL is part of a series. Update just the event whose ID is in in the URL, all events in the series, or the given event and all those following. Some updates may create a new series. For example, changing the start time of this and all following events from the middle of a series.

Allowed values: one, all, following

calendar_event[blackout_date] boolean

If the blackout_date is true, this event represents a holiday or some other special day that does not count in course pacing.

Example Request:

curl 'https://<canvas>/api/v1/calendar_events/234' \
     -X PUT \
     -F 'calendar_event[title]=Epic Paintball Fight!' \
     -H "Authorization: Bearer <token>"

Delete a calendar event CalendarEventsApiController#destroy

DELETE /api/v1/calendar_events/:id

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

Delete an event from the calendar and return the deleted event

Request Parameters:

Parameter Type Description
cancel_reason string

Reason for deleting/canceling the event.

which string

Valid if the event whose ID is in the URL is part of a series. Delete just the event whose ID is in in the URL, all events in the series, or the given event and all those following.

Allowed values: one, all, following

Example Request:

curl 'https://<canvas>/api/v1/calendar_events/234' \
     -X DELETE \
     -F 'cancel_reason=Greendale layed off the janitorial staff :(' \
     -F 'which=following'
     -H "Authorization: Bearer <token>"

Save enabled account calendars CalendarEventsApiController#save_enabled_account_calendars

POST /api/v1/calendar_events/save_enabled_account_calendars

Scope: url:POST|/api/v1/calendar_events/save_enabled_account_calendars

Creates and updates the enabled_account_calendars and mark_feature_as_seen user preferences

Request Parameters:

Parameter Type Description
mark_feature_as_seen boolean

Flag to mark account calendars feature as seen

enabled_account_calendars[] Array

An array of account Ids to remember in the calendars list of the user

Example Request:

curl 'https://<canvas>/api/v1/calendar_events/save_enabled_account_calendars' \
     -X POST \
     -F 'mark_feature_as_seen=true' \
     -F 'enabled_account_calendars[]=1' \
     -F 'enabled_account_calendars[]=2' \
     -H "Authorization: Bearer <token>"

Set a course timetable CalendarEventsApiController#set_course_timetable

POST /api/v1/courses/:course_id/calendar_events/timetable

Scope: url:POST|/api/v1/courses/:course_id/calendar_events/timetable

Creates and updates “timetable” events for a course. Can automaticaly generate a series of calendar events based on simple schedules (e.g. “Monday and Wednesday at 2:00pm” )

Existing timetable events for the course and course sections will be updated if they still are part of the timetable. Otherwise, they will be deleted.

Request Parameters:

Parameter Type Description
timetables[course_section_id][] Array

An array of timetable objects for the course section specified by course_section_id. If course_section_id is set to “all”, events will be created for the entire course.

timetables[course_section_id][][weekdays] string

A comma-separated list of abbreviated weekdays (Mon-Monday, Tue-Tuesday, Wed-Wednesday, Thu-Thursday, Fri-Friday, Sat-Saturday, Sun-Sunday)

timetables[course_section_id][][start_time] string

Time to start each event at (e.g. “9:00 am”)

timetables[course_section_id][][end_time] string

Time to end each event at (e.g. “9:00 am”)

timetables[course_section_id][][location_name] string

A location name to set for each event

Example Request:

curl 'https://<canvas>/api/v1/calendar_events/timetable' \
     -X POST \
     -F 'timetables[all][][weekdays]=Mon,Wed,Fri' \
     -F 'timetables[all][][start_time]=11:00 am' \
     -F 'timetables[all][][end_time]=11:50 am' \
     -F 'timetables[all][][location_name]=Room 237' \
     -H "Authorization: Bearer <token>"

Get course timetable CalendarEventsApiController#get_course_timetable

GET /api/v1/courses/:course_id/calendar_events/timetable

Scope: url:GET|/api/v1/courses/:course_id/calendar_events/timetable

Returns the last timetable set by the Set a course timetable endpoint

Create or update events directly for a course timetable CalendarEventsApiController#set_course_timetable_events

POST /api/v1/courses/:course_id/calendar_events/timetable_events

Scope: url:POST|/api/v1/courses/:course_id/calendar_events/timetable_events

Creates and updates “timetable” events for a course or course section. Similar to setting a course timetable, but instead of generating a list of events based on a timetable schedule, this endpoint expects a complete list of events.

Request Parameters:

Parameter Type Description
course_section_id string

Events will be created for the course section specified by course_section_id. If not present, events will be created for the entire course.

events[] Array

An array of event objects to use.

events[][start_at] DateTime

Start time for the event

events[][end_at] DateTime

End time for the event

events[][location_name] string

Location name for the event

events[][code] string

A unique identifier that can be used to update the event at a later time If one is not specified, an identifier will be generated based on the start and end times

events[][title] string

Title for the meeting. If not present, will default to the associated course’s name

List collaborations CollaborationsController#api_index

GET /api/v1/courses/:course_id/collaborations

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

GET /api/v1/groups/:group_id/collaborations

Scope: url:GET|/api/v1/groups/:group_id/collaborations

A paginated list of collaborations the current user has access to in the context of the course provided in the url. NOTE: this only returns ExternalToolCollaboration type collaborations.

curl https://<canvas>/api/v1/courses/1/collaborations/
Returns a list of Collaboration objects

List members of a collaboration. CollaborationsController#members

GET /api/v1/collaborations/:id/members

Scope: url:GET|/api/v1/collaborations/:id/members

A paginated list of the collaborators of a given collaboration

Request Parameters:

Parameter Type Description
include[] string
  • “collaborator_lti_id”: Optional information to include with each member. Represents an identifier to be used for the member in an LTI context.

  • “avatar_image_url”: Optional information to include with each member. The url for the avatar of a collaborator with type ‘user’.

Allowed values: collaborator_lti_id, avatar_image_url

Example Request:

curl https://<canvas>/api/v1/courses/1/collaborations/1/members
Returns a list of Collaborator objects

List potential members CollaborationsController#potential_collaborators

GET /api/v1/courses/:course_id/potential_collaborators

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

GET /api/v1/groups/:group_id/potential_collaborators

Scope: url:GET|/api/v1/groups/:group_id/potential_collaborators

A paginated list of the users who can potentially be added to a collaboration in the given context.

For courses, this consists of all enrolled users. For groups, it is comprised of the group members plus the admins of the course containing the group.

Returns a list of User objects

List of CommMessages for a user CommMessagesApiController#index

GET /api/v1/comm_messages

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

Retrieve a paginated list of messages sent to a user.

Request Parameters:

Parameter Type Description
user_id Required string

The user id for whom you want to retrieve CommMessages

start_time DateTime

The beginning of the time range you want to retrieve message from. Up to a year prior to the current date is available.

end_time DateTime

The end of the time range you want to retrieve messages for. Up to a year prior to the current date is available.

Returns a list of CommMessage objects

List user communication channels CommunicationChannelsController#index

GET /api/v1/users/:user_id/communication_channels

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

Returns a paginated list of communication channels for the specified user, sorted by position.

Example Request:

curl https://<canvas>/api/v1/users/12345/communication_channels \
     -H 'Authorization: Bearer <token>'
Returns a list of CommunicationChannel objects

Create a communication channel CommunicationChannelsController#create

POST /api/v1/users/:user_id/communication_channels

Scope: url:POST|/api/v1/users/:user_id/communication_channels

Creates a new communication channel for the specified user.

Request Parameters:

Parameter Type Description
communication_channel[address] Required string

An email address or SMS number. Not required for “push” type channels.

communication_channel[type] Required string

The type of communication channel.

In order to enable push notification support, the server must be properly configured (via ‘sns_creds` in Vault) to communicate with Amazon Simple Notification Services, and the developer key used to create the access token from this request must have an SNS ARN configured on it.

Allowed values: email, sms, push

communication_channel[token] string

A registration id, device token, or equivalent token given to an app when registering with a push notification provider. Only valid for “push” type channels.

skip_confirmation boolean

Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.

Example Request:

curl https://<canvas>/api/v1/users/1/communication_channels \
     -H 'Authorization: Bearer <token>' \
     -d 'communication_channel[address]=new@example.com' \
     -d 'communication_channel[type]=email' \
Returns a CommunicationChannel object

Delete a communication channel CommunicationChannelsController#destroy

DELETE /api/v1/users/:user_id/communication_channels/:id

Scope: url:DELETE|/api/v1/users/:user_id/communication_channels/:id

DELETE /api/v1/users/:user_id/communication_channels/:type/:address

Scope: url:DELETE|/api/v1/users/:user_id/communication_channels/:type/:address

Delete an existing communication channel.

Example Request:

curl https://<canvas>/api/v1/users/5/communication_channels/3
     -H 'Authorization: Bearer <token>
     -X DELETE
Returns a CommunicationChannel object

Delete a push notification endpoint CommunicationChannelsController#delete_push_token

DELETE /api/v1/users/self/communication_channels/push

Scope: url:DELETE|/api/v1/users/self/communication_channels/push

Example Request:

curl https://<canvas>/api/v1/users/self/communication_channels/push
     -H 'Authorization: Bearer <token>
     -X DELETE
     -d 'push_token=<push_token>'

List conferences ConferencesController#index

GET /api/v1/courses/:course_id/conferences

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

GET /api/v1/groups/:group_id/conferences

Scope: url:GET|/api/v1/groups/:group_id/conferences

Retrieve the paginated list of conferences for this context

This API returns a JSON object containing the list of conferences, the key for the list of conferences is “conferences”

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/conferences' \
    -H "Authorization: Bearer <token>"

curl 'https://<canvas>/api/v1/groups/<group_id>/conferences' \
    -H "Authorization: Bearer <token>"
Returns a list of Conference objects

List conferences for the current user ConferencesController#for_user

GET /api/v1/conferences

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

Retrieve the paginated list of conferences for all courses and groups the current user belongs to

This API returns a JSON object containing the list of conferences. The key for the list of conferences is “conferences”.

Request Parameters:

Parameter Type Description
state string

If set to “live”, returns only conferences that are live (i.e., have started and not finished yet). If omitted, returns all conferences for this user’s groups and courses.

Example Request:

curl 'https://<canvas>/api/v1/conferences' \
    -H "Authorization: Bearer <token>"
Returns a list of Conference objects

List content exports ContentExportsApiController#index

GET /api/v1/courses/:course_id/content_exports

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

GET /api/v1/groups/:group_id/content_exports

Scope: url:GET|/api/v1/groups/:group_id/content_exports

GET /api/v1/users/:user_id/content_exports

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

A paginated list of the past and pending content export jobs for a course, group, or user. Exports are returned newest first.

Returns a list of ContentExport objects

Show content export ContentExportsApiController#show

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

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

GET /api/v1/groups/:group_id/content_exports/:id

Scope: url:GET|/api/v1/groups/:group_id/content_exports/:id

GET /api/v1/users/:user_id/content_exports/:id

Scope: url:GET|/api/v1/users/:user_id/content_exports/:id

Get information about a single content export.

Returns a ContentExport object

Export content ContentExportsApiController#create

POST /api/v1/courses/:course_id/content_exports

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

POST /api/v1/groups/:group_id/content_exports

Scope: url:POST|/api/v1/groups/:group_id/content_exports

POST /api/v1/users/:user_id/content_exports

Scope: url:POST|/api/v1/users/:user_id/content_exports

Begin a content export job for a course, group, or user.

You can use the Progress API to track the progress of the export. The migration’s progress is linked to with the progress_url value.

When the export completes, use the Show content export endpoint to retrieve a download URL for the exported content.

Request Parameters:

Parameter Type Description
export_type Required string
“common_cartridge”

Export the contents of the course in the Common Cartridge (.imscc) format

“qti”

Export quizzes from a course in the QTI format

“zip”

Export files from a course, group, or user in a zip file

Allowed values: common_cartridge, qti, zip

skip_notifications boolean

Don’t send the notifications about the export to the user. Default: false

select Hash

The select parameter allows exporting specific data. The keys are object types like ‘files’, ‘folders’, ‘pages’, etc. The value for each key is a list of object ids. An id can be an integer or a string.

Multiple object types can be selected in the same call. However, not all object types are valid for every export_type. Common Cartridge supports all object types. Zip and QTI only support the object types as described below.

“folders”

Also supported for zip export_type.

“files”

Also supported for zip export_type.

“quizzes”

Also supported for qti export_type.

Allowed values: folders, files, attachments, quizzes, assignments, announcements, calendar_events, discussion_topics, modules, module_items, pages, rubrics

Returns a ContentExport object

List migration issues MigrationIssuesController#index

GET /api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues

Scope: url:GET|/api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues

GET /api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues

Scope: url:GET|/api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues

GET /api/v1/groups/:group_id/content_migrations/:content_migration_id/migration_issues

Scope: url:GET|/api/v1/groups/:group_id/content_migrations/:content_migration_id/migration_issues

GET /api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues

Scope: url:GET|/api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues

Returns paginated migration issues

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues \
    -H 'Authorization: Bearer <token>'
Returns a list of MigrationIssue objects

Get a migration issue MigrationIssuesController#show

GET /api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:GET|/api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues/:id

GET /api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:GET|/api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues/:id

GET /api/v1/groups/:group_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:GET|/api/v1/groups/:group_id/content_migrations/:content_migration_id/migration_issues/:id

GET /api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:GET|/api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues/:id

Returns data on an individual migration issue

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues/<id> \
    -H 'Authorization: Bearer <token>'
Returns a MigrationIssue object

Update a migration issue MigrationIssuesController#update

PUT /api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:PUT|/api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues/:id

PUT /api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:PUT|/api/v1/courses/:course_id/content_migrations/:content_migration_id/migration_issues/:id

PUT /api/v1/groups/:group_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:PUT|/api/v1/groups/:group_id/content_migrations/:content_migration_id/migration_issues/:id

PUT /api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues/:id

Scope: url:PUT|/api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues/:id

Update the workflow_state of a migration issue

Request Parameters:

Parameter Type Description
workflow_state Required string

Set the workflow_state of the issue.

Allowed values: active, resolved

Example Request:

curl -X PUT https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues/<id> \
     -H 'Authorization: Bearer <token>' \
     -F 'workflow_state=resolved'
Returns a MigrationIssue object

List content migrations ContentMigrationsController#index

GET /api/v1/accounts/:account_id/content_migrations

Scope: url:GET|/api/v1/accounts/:account_id/content_migrations

GET /api/v1/courses/:course_id/content_migrations

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

GET /api/v1/groups/:group_id/content_migrations

Scope: url:GET|/api/v1/groups/:group_id/content_migrations

GET /api/v1/users/:user_id/content_migrations

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

Returns paginated content migrations

Example Request:

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

Get a content migration ContentMigrationsController#show

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

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

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

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

GET /api/v1/groups/:group_id/content_migrations/:id

Scope: url:GET|/api/v1/groups/:group_id/content_migrations/:id

GET /api/v1/users/:user_id/content_migrations/:id

Scope: url:GET|/api/v1/users/:user_id/content_migrations/:id

Returns data on an individual content migration

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<id> \
    -H 'Authorization: Bearer <token>'
Returns a ContentMigration object

Create a content migration ContentMigrationsController#create

POST /api/v1/accounts/:account_id/content_migrations

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

POST /api/v1/courses/:course_id/content_migrations

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

POST /api/v1/groups/:group_id/content_migrations

Scope: url:POST|/api/v1/groups/:group_id/content_migrations

POST /api/v1/users/:user_id/content_migrations

Scope: url:POST|/api/v1/users/:user_id/content_migrations

Create a content migration. If the migration requires a file to be uploaded the actual processing of the file will start once the file upload process is completed. File uploading works as described in the File Upload Documentation except that the values are set on a pre_attachment sub-hash.

For migrations that don’t require a file to be uploaded, like course copy, the processing will begin as soon as the migration is created.

You can use the Progress API to track the progress of the migration. The migration’s progress is linked to with the progress_url value.

The two general workflows are:

If no file upload is needed:

  1. POST to create

  2. Use the Progress specified in progress_url to monitor progress

For file uploading:

  1. POST to create with file info in pre_attachment

  2. Do file upload processing using the data in the pre_attachment data

  3. GET the ContentMigration

  4. Use the Progress specified in progress_url to monitor progress

(required if doing .zip file upload)

Request Parameters:

Parameter Type Description
migration_type Required string

The type of the migration. Use the Migrator endpoint to see all available migrators. Default allowed values: canvas_cartridge_importer, common_cartridge_importer, course_copy_importer, zip_file_importer, qti_converter, moodle_converter

pre_attachment[name] string

Required if uploading a file. This is the first step in uploading a file to the content migration. See the File Upload Documentation for details on the file upload workflow.

pre_attachment[*] string

Other file upload properties, See File Upload Documentation

settings[file_url] string

A URL to download the file from. Must not require authentication.

settings[content_export_id] string

The id of a ContentExport to import. This allows you to import content previously exported from Canvas without needing to download and re-upload it.

settings[source_course_id] string

The course to copy from for a course copy migration. (required if doing course copy)

settings[folder_id] string

The folder to unzip the .zip file into for a zip_file_import.

settings[overwrite_quizzes] boolean

Whether to overwrite quizzes with the same identifiers between content packages.

settings[question_bank_id] integer

The existing question bank ID to import questions into if not specified in the content package.

settings[question_bank_name] string

The question bank to import questions into if not specified in the content package, if both bank id and name are set, id will take precedence.

settings[insert_into_module_id] integer

The id of a module in the target course. This will add all imported items (that can be added to a module) to the given module.

settings[insert_into_module_type] string

If provided (and insert_into_module_id is supplied), only add objects of the specified type to the module.

Allowed values: assignment, discussion_topic, file, page, quiz

settings[insert_into_module_position] integer

The (1-based) position to insert the imported items into the course (if insert_into_module_id is supplied). If this parameter is omitted, items will be added to the end of the module.

settings[move_to_assignment_group_id] integer

The id of an assignment group in the target course. If provided, all imported assignments will be moved to the given assignment group.

settings[importer_skips] Array

Set of importers to skip, even if otherwise selected by migration settings.

Allowed values: all_course_settings, visibility_settings

settings[import_blueprint_settings] boolean

Import the “use as blueprint course” setting as well as the list of locked items from the source course or package. The destination course must not be associated with an existing blueprint course and cannot have any student or observer enrollments.

date_shift_options[shift_dates] boolean

Whether to shift dates in the copied course

date_shift_options[old_start_date] Date

The original start date of the source content/course

date_shift_options[old_end_date] Date

The original end date of the source content/course

date_shift_options[new_start_date] Date

The new start date for the content/course

date_shift_options[new_end_date] Date

The new end date for the source content/course

date_shift_options[day_substitutions][X] integer

Move anything scheduled for day ‘X’ to the specified day. (0-Sunday, 1-Monday, 2-Tuesday, 3-Wednesday, 4-Thursday, 5-Friday, 6-Saturday)

date_shift_options[remove_dates] boolean

Whether to remove dates in the copied course. Cannot be used in conjunction with shift_dates.

selective_import boolean

If set, perform a selective import instead of importing all content. The migration will identify the contents of the package and then stop in the waiting_for_select workflow state. At this point, use the List items endpoint to enumerate the contents of the package, identifying the copy parameters for the desired content. Then call the Update endpoint and provide these copy parameters to start the import.

select Hash

For course_copy_importer migrations, this parameter allows you to select the objects to copy without using the selective_import argument and waiting_for_select state as is required for uploaded imports (though that workflow is also supported for course copy migrations). The keys are object types like ‘files’, ‘folders’, ‘pages’, etc. The value for each key is a list of object ids. An id can be an integer or a string. Multiple object types can be selected in the same call.

Allowed values: folders, files, attachments, quizzes, assignments, announcements, calendar_events, discussion_topics, modules, module_items, pages, rubrics

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/content_migrations' \
     -F 'migration_type=common_cartridge_importer' \
     -F 'settings[question_bank_name]=importquestions' \
     -F 'date_shift_options[old_start_date]=1999-01-01' \
     -F 'date_shift_options[new_start_date]=2013-09-01' \
     -F 'date_shift_options[old_end_date]=1999-04-15' \
     -F 'date_shift_options[new_end_date]=2013-12-15' \
     -F 'date_shift_options[day_substitutions][1]=2' \
     -F 'date_shift_options[day_substitutions][2]=3' \
     -F 'date_shift_options[shift_dates]=true' \
     -F 'pre_attachment[name]=mycourse.imscc' \
     -F 'pre_attachment[size]=12345' \
     -H 'Authorization: Bearer <token>'
Returns a ContentMigration object

Update a content migration ContentMigrationsController#update

PUT /api/v1/accounts/:account_id/content_migrations/:id

Scope: url:PUT|/api/v1/accounts/:account_id/content_migrations/:id

PUT /api/v1/courses/:course_id/content_migrations/:id

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

PUT /api/v1/groups/:group_id/content_migrations/:id

Scope: url:PUT|/api/v1/groups/:group_id/content_migrations/:id

PUT /api/v1/users/:user_id/content_migrations/:id

Scope: url:PUT|/api/v1/users/:user_id/content_migrations/:id

Update a content migration. Takes same arguments as create except that you can’t change the migration type. However, changing most settings after the migration process has started will not do anything. Generally updating the content migration will be used when there is a file upload problem, or when importing content selectively. If the first upload has a problem you can supply new pre_attachment values to start the process again.

Returns a ContentMigration object

List Migration Systems ContentMigrationsController#available_migrators

GET /api/v1/accounts/:account_id/content_migrations/migrators

Scope: url:GET|/api/v1/accounts/:account_id/content_migrations/migrators

GET /api/v1/courses/:course_id/content_migrations/migrators

Scope: url:GET|/api/v1/courses/:course_id/content_migrations/migrators

GET /api/v1/groups/:group_id/content_migrations/migrators

Scope: url:GET|/api/v1/groups/:group_id/content_migrations/migrators

GET /api/v1/users/:user_id/content_migrations/migrators

Scope: url:GET|/api/v1/users/:user_id/content_migrations/migrators

Lists the currently available migration types. These values may change.

Returns a list of Migrator objects

List items for selective import ContentMigrationsController#content_list

GET /api/v1/accounts/:account_id/content_migrations/:id/selective_data

Scope: url:GET|/api/v1/accounts/:account_id/content_migrations/:id/selective_data

GET /api/v1/courses/:course_id/content_migrations/:id/selective_data

Scope: url:GET|/api/v1/courses/:course_id/content_migrations/:id/selective_data

GET /api/v1/groups/:group_id/content_migrations/:id/selective_data

Scope: url:GET|/api/v1/groups/:group_id/content_migrations/:id/selective_data

GET /api/v1/users/:user_id/content_migrations/:id/selective_data

Scope: url:GET|/api/v1/users/:user_id/content_migrations/:id/selective_data

Enumerates the content available for selective import in a tree structure. Each node provides a property copy argument that can be supplied to the Update endpoint to selectively copy the content associated with that tree node and its children. Each node may also provide a sub_items_url or an array of sub_items which you can use to obtain copy parameters for a subset of the resources in a given node.

If no type is sent you will get a list of the top-level sections in the content. It will look something like this:

[{
  "type": "course_settings",
  "property": "copy[all_course_settings]",
  "title": "Course Settings"
},
{
  "type": "context_modules",
  "property": "copy[all_context_modules]",
  "title": "Modules",
  "count": 5,
  "sub_items_url": "http://example.com/api/v1/courses/22/content_migrations/77/selective_data?type=context_modules"
},
{
  "type": "assignments",
  "property": "copy[all_assignments]",
  "title": "Assignments",
  "count": 2,
  "sub_items_url": "http://localhost:3000/api/v1/courses/22/content_migrations/77/selective_data?type=assignments"
}]

When a type is provided, nodes may be further divided via sub_items. For example, using type=assignments results in a node for each assignment group and a sub_item for each assignment, like this:

[{
  "type": "assignment_groups",
  "title": "An Assignment Group",
  "property": "copy[assignment_groups][id_i855cf145e5acc7435e1bf1c6e2126e5f]",
  "sub_items": [{
      "type": "assignments",
      "title": "Assignment 1",
      "property": "copy[assignments][id_i2102a7fa93b29226774949298626719d]"
  }, {
      "type": "assignments",
      "title": "Assignment 2",
      "property": "copy[assignments][id_i310cba275dc3f4aa8a3306bbbe380979]"
  }]
}]

To import the items corresponding to a particular tree node, use the property as a parameter to the Update endpoint and assign a value of 1, for example:

copy[assignments][id_i310cba275dc3f4aa8a3306bbbe380979]=1

You can include multiple copy parameters to selectively import multiple items or groups of items.

Request Parameters:

Parameter Type Description
type string

The type of content to enumerate.

Allowed values: context_modules, assignments, quizzes, assessment_question_banks, discussion_topics, wiki_pages, context_external_tools, tool_profiles, announcements, calendar_events, rubrics, groups, learning_outcomes, attachments

Get asset id mapping ContentMigrationsController#asset_id_mapping

GET /api/v1/courses/:course_id/content_migrations/:id/asset_id_mapping

Scope: url:GET|/api/v1/courses/:course_id/content_migrations/:id/asset_id_mapping

Given a complete course copy or blueprint import content migration, return a mapping of asset ids from the source course to the destination course that were copied in this migration or an earlier one with the same course pair and migration_type (course copy or blueprint).

The returned object’s keys are asset types as they appear in API URLs (announcements, assignments, discussion_topics, files, module_items, modules, pages, and quizzes). The values are a mapping from id in source course to id in destination course for objects of this type.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<id>/asset_id_mapping \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "assignments": {"13": "740", "14": "741"},
  "discussion_topics": {"15": "743", "16": "744"}
}

Get current settings for account or course CspSettingsController#get_csp_settings

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/courses/:course_id/csp_settings

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

GET /api/v1/accounts/:account_id/csp_settings

Scope: url:GET|/api/v1/accounts/:account_id/csp_settings

Update multiple modules in an account.

API response field:

  • enabled

    Whether CSP is enabled.

  • inherited

    Whether the current CSP settings are inherited from a parent account.

  • settings_locked

    Whether current CSP settings can be overridden by sub-accounts and courses.

  • effective_whitelist

    If enabled, lists the currently allowed domains (includes domains automatically allowed through external tools).

  • tools_whitelist

    (Account-only) Lists the automatically allowed domains with their respective external tools

  • current_account_whitelist

    (Account-only) Lists the current list of domains explicitly allowed by this account. (Note: this list will not take effect unless CSP is explicitly enabled on this account)

Enable, disable, or clear explicit CSP setting CspSettingsController#set_csp_setting

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

PUT /api/v1/courses/:course_id/csp_settings

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

PUT /api/v1/accounts/:account_id/csp_settings

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

Either explicitly sets CSP to be on or off for courses and sub-accounts, or clear the explicit settings to default to those set by a parent account

Note: If “inherited” and “settings_locked” are both true for this account or course, then the CSP setting cannot be modified.

Request Parameters:

Parameter Type Description
status Required string

If set to “enabled” for an account, CSP will be enabled for all its courses and sub-accounts (that have not explicitly enabled or disabled it), using the allowed domains set on this account. If set to “disabled”, CSP will be disabled for this account or course and for all sub-accounts that have not explicitly re-enabled it. If set to “inherited”, this account or course will reset to the default state where CSP settings are inherited from the first parent account to have them explicitly set.

Allowed values: enabled, disabled, inherited

Lock or unlock current CSP settings for sub-accounts and courses CspSettingsController#set_csp_lock

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

PUT /api/v1/accounts/:account_id/csp_settings/lock

Scope: url:PUT|/api/v1/accounts/:account_id/csp_settings/lock

Can only be set if CSP is explicitly enabled or disabled on this account (i.e. “inherited” is false).

Request Parameters:

Parameter Type Description
settings_locked Required boolean

Whether sub-accounts and courses will be prevented from overriding settings inherited from this account.

Add an allowed domain to account CspSettingsController#add_domain

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

POST /api/v1/accounts/:account_id/csp_settings/domains

Scope: url:POST|/api/v1/accounts/:account_id/csp_settings/domains

Adds an allowed domain for the current account. Note: this will not take effect unless CSP is explicitly enabled on this account.

Request Parameters:

Parameter Type Description
domain Required string

no description

Add multiple allowed domains to an account CspSettingsController#add_multiple_domains

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

POST /api/v1/accounts/:account_id/csp_settings/domains/batch_create

Scope: url:POST|/api/v1/accounts/:account_id/csp_settings/domains/batch_create

Adds multiple allowed domains for the current account. Note: this will not take effect unless CSP is explicitly enabled on this account.

Request Parameters:

Parameter Type Description
domains Required Array

no description

Remove a domain from account CspSettingsController#remove_domain

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

DELETE /api/v1/accounts/:account_id/csp_settings/domains

Scope: url:DELETE|/api/v1/accounts/:account_id/csp_settings/domains

Removes an allowed domain from the current account.

Request Parameters:

Parameter Type Description
domain Required string

no description

Create a content share ContentSharesController#create

POST /api/v1/users/:user_id/content_shares

Scope: url:POST|/api/v1/users/:user_id/content_shares

Share content directly between two or more users

Request Parameters:

Parameter Type Description
receiver_ids Required Array

IDs of users to share the content with.

content_type Required string

Type of content you are sharing.

Allowed values: assignment, discussion_topic, page, quiz, module, module_item

content_id Required integer

The id of the content that you are sharing

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares \
      -d 'content_type=assignment' \
      -d 'content_id=1' \
      -H 'Authorization: Bearer <token>' \
      -X POST
Returns a ContentShare object

List content shares ContentSharesController#index

GET /api/v1/users/:user_id/content_shares/sent

Scope: url:GET|/api/v1/users/:user_id/content_shares/sent

GET /api/v1/users/:user_id/content_shares/received

Scope: url:GET|/api/v1/users/:user_id/content_shares/received

Return a paginated list of content shares a user has sent or received. Use self as the user_id to retrieve your own content shares. Only linked observers and administrators may view other users’ content shares.

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares/received'
Returns a list of ContentShare objects

Get unread shares count ContentSharesController#unread_count

GET /api/v1/users/:user_id/content_shares/unread_count

Scope: url:GET|/api/v1/users/:user_id/content_shares/unread_count

Return the number of content shares a user has received that have not yet been read. Use self as the user_id to retrieve your own content shares. Only linked observers and administrators may view other users’ content shares.

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares/unread_count'

Get content share ContentSharesController#show

GET /api/v1/users/:user_id/content_shares/:id

Scope: url:GET|/api/v1/users/:user_id/content_shares/:id

Return information about a single content share. You may use self as the user_id to retrieve your own content share.

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares/123'
Returns a ContentShare object

Remove content share ContentSharesController#destroy

DELETE /api/v1/users/:user_id/content_shares/:id

Scope: url:DELETE|/api/v1/users/:user_id/content_shares/:id

Remove a content share from your list. Use self as the user_id. Note that this endpoint does not delete other users’ copies of the content share.

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/users/self/content_shares/123'

Add users to content share ContentSharesController#add_users

POST /api/v1/users/:user_id/content_shares/:id/add_users

Scope: url:POST|/api/v1/users/:user_id/content_shares/:id/add_users

Send a previously created content share to additional users

Request Parameters:

Parameter Type Description
receiver_ids Array

IDs of users to share the content with.

Example Request:

curl -X POST 'https://<canvas>/api/v1/users/self/content_shares/123/add_users?receiver_ids[]=789'
Returns a ContentShare object

Update a content share ContentSharesController#update

PUT /api/v1/users/:user_id/content_shares/:id

Scope: url:PUT|/api/v1/users/:user_id/content_shares/:id

Mark a content share read or unread

Request Parameters:

Parameter Type Description
read_state string

Read state for the content share

Allowed values: read, unread

Example Request:

curl -X PUT 'https://<canvas>/api/v1/users/self/content_shares/123?read_state=read'
Returns a ContentShare object

List conversations ConversationsController#index

GET /api/v1/conversations

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

Returns the paginated list of conversations for the current user, most recent ones first.

Request Parameters:

Parameter Type Description
scope string

When set, only return conversations of the specified type. For example, set to “unread” to return only conversations that haven’t been read. The default behavior is to return all non-archived conversations (i.e. read and unread).

Allowed values: unread, starred, archived

filter[] string

When set, only return conversations for the specified courses, groups or users. The id should be prefixed with its type, e.g. “user_123” or “course_456”. Can be an array (by setting “filter[]”) or single value (by setting “filter”)

filter_mode string

When filter[] contains multiple filters, combine them with this mode, filtering conversations that at have at least all of the contexts (“and”) or at least one of the contexts (“or”)

Allowed values: and, or, default or

interleave_submissions boolean

(Obsolete) Submissions are no longer linked to conversations. This parameter is ignored.

include_all_conversation_ids boolean

Default is false. If true, the top-level element of the response will be an object rather than an array, and will have the keys “conversations” which will contain the paged conversation data, and “conversation_ids” which will contain the ids of all conversations under this scope/filter in the same order.

include[] string
“participant_avatars”

Optionally include an “avatar_url” key for each user participanting in the conversation

Allowed values: participant_avatars

API response field:

  • id

    The unique identifier for the conversation.

  • subject

    The subject of the conversation.

  • workflow_state

    The current state of the conversation (read, unread or archived)

  • last_message

    A <=100 character preview from the most recent message

  • last_message_at

    The timestamp of the latest message

  • message_count

    The number of messages in this conversation

  • subscribed

    Indicates whether the user is actively subscribed to the conversation

  • private

    Indicates whether this is a private conversation (i.e. audience of one)

  • starred

    Whether the conversation is starred

  • properties

    Additional conversation flags (last_author, attachments, media_objects). Each listed property means the flag is set to true (i.e. the current user is the most recent author, there are attachments, or there are media objects)

  • audience

    Array of user ids who are involved in the conversation, ordered by participation level, then alphabetical. Excludes current user, unless this is a monologue.

  • audience_contexts

    Most relevant shared contexts (courses and groups) between current user and other participants. If there is only one participant, it will also include that user’s enrollment(s)/ membership type(s) in each course/group

  • avatar_url

    URL to appropriate icon for this conversation (custom, individual or group avatar, depending on audience)

  • participants

    Array of users (id, name, full_name) participating in the conversation. Includes current user. If ‘include[]=participant_avatars` was passed as an argument, each user in the array will also have an “avatar_url” field

  • visible

    Boolean, indicates whether the conversation is visible under the current scope and filter. This attribute is always true in the index API response, and is primarily useful in create/update responses so that you can know if the record should be displayed in the UI. The default scope is assumed, unless a scope or filter is passed to the create/update API call.

Example Response:

[
  {
    "id": 2,
    "subject": "conversations api example",
    "workflow_state": "unread",
    "last_message": "sure thing, here's the file",
    "last_message_at": "2011-09-02T12:00:00Z",
    "message_count": 2,
    "subscribed": true,
    "private": true,
    "starred": false,
    "properties": ["attachments"],
    "audience": [2],
    "audience_contexts": {"courses": {"1": ["StudentEnrollment"]}, "groups": {}},
    "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
    "participants": [
      {"id": 1, "name": "Joe", "full_name": "Joe TA"},
      {"id": 2, "name": "Jane", "full_name": "Jane Teacher"}
    ],
    "visible": true,
    "context_name": "Canvas 101"
  }
]
Returns a list of Conversation objects

Create a conversation ConversationsController#create

POST /api/v1/conversations

Scope: url:POST|/api/v1/conversations

Create a new conversation with one or more recipients. If there is already an existing private conversation with the given recipients, it will be reused.

Request Parameters:

Parameter Type Description
recipients[] Required string

An array of recipient ids. These may be user ids or course/group ids prefixed with “course_” or “group_” respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3. If the course/group has over 100 enrollments, ‘bulk_message’ and ‘group_conversation’ must be set to true.

subject string

The subject of the conversation. This is ignored when reusing a conversation. Maximum length is 255 characters.

body Required string

The message to be sent

force_new boolean

Forces a new message to be created, even if there is an existing private conversation.

group_conversation boolean

Defaults to false. When false, individual private conversations will be created with each recipient. If true, this will be a group conversation (i.e. all recipients may see all messages and replies). Must be set true if the number of recipients is over the set maximum (default is 100).

attachment_ids[] string

An array of attachments ids. These must be files that have been previously uploaded to the sender’s “conversation attachments” folder.

media_comment_id string

Media comment id of an audio or video file to be associated with this message.

media_comment_type string

Type of the associated media file

Allowed values: audio, video

mode string

Determines whether the messages will be created/sent synchronously or asynchronously. Defaults to sync, and this option is ignored if this is a group conversation or there is just one recipient (i.e. it must be a bulk private message). When sent async, the response will be an empty array (batch status can be queried via the batches API)

Allowed values: sync, async

scope string

Used when generating “visible” in the API response. See the explanation under the index API action

Allowed values: unread, starred, archived

filter[] string

Used when generating “visible” in the API response. See the explanation under the index API action

filter_mode string

Used when generating “visible” in the API response. See the explanation under the index API action

Allowed values: and, or, default or

context_code string

The course or group that is the context for this conversation. Same format as courses or groups in the recipients argument.

Get running batches ConversationsController#batches

GET /api/v1/conversations/batches

Scope: url:GET|/api/v1/conversations/batches

Returns any currently running conversation batches for the current user. Conversation batches are created when a bulk private message is sent asynchronously (see the mode argument to the create API action).

Example Response:

[
  {
    "id": 1,
    "subject": "conversations api example",
    "workflow_state": "created",
    "completion": 0.1234,
    "tags": [],
    "message":
    {
      "id": 1,
      "created_at": "2011-09-02T10:00:00Z",
      "body": "quick reminder, no class tomorrow",
      "author_id": 1,
      "generated": false,
      "media_comment": null,
      "forwarded_messages": [],
      "attachments": []
    }
  }
]

Get a single conversation ConversationsController#show

GET /api/v1/conversations/:id

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

Returns information for a single conversation for the current user. Response includes all fields that are present in the list/index action as well as messages and extended participant information.

Request Parameters:

Parameter Type Description
interleave_submissions boolean

(Obsolete) Submissions are no longer linked to conversations. This parameter is ignored.

scope string

Used when generating “visible” in the API response. See the explanation under the index API action

Allowed values: unread, starred, archived

filter[] string

Used when generating “visible” in the API response. See the explanation under the index API action

filter_mode string

Used when generating “visible” in the API response. See the explanation under the index API action

Allowed values: and, or, default or

auto_mark_as_read boolean

Default true. If true, unread conversations will be automatically marked as read. This will default to false in a future API release, so clients should explicitly send true if that is the desired behavior.

API response field:

  • participants

    Array of relevant users. Includes current user. If there are forwarded messages in this conversation, the authors of those messages will also be included, even if they are not participating in this conversation. Fields include:

  • messages

    Array of messages, newest first. Fields include:

    id

    The unique identifier for the message

    created_at

    The timestamp of the message

    body

    The actual message body

    author_id

    The id of the user who sent the message (see audience, participants)

    generated

    If true, indicates this is a system-generated message (e.g. “Bob added Alice to the conversation”)

    media_comment

    Audio/video comment data for this message (if applicable). Fields include: display_name, content-type, media_id, media_type, url

    forwarded_messages

    If this message contains forwarded messages, they will be included here (same format as this list). Note that those messages may have forwarded messages of their own, etc.

    attachments

    Array of attachments for this message. Fields include: display_name, content-type, filename, url

  • submissions

    (Obsolete) Array of assignment submissions having comments relevant to this conversation. Submissions are no longer linked to conversations. This field will always be nil or empty.

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "unread",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": ["attachments"],
  "audience": [2],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
  "participants": [
    {"id": 1, "name": "Joe", "full_name": "Joe TA"},
    {"id": 2, "name": "Jane", "full_name": "Jane Teacher"},
    {"id": 3, "name": "Bob", "full_name": "Bob Student"}
  ],
  "messages":
    [
      {
        "id": 3,
        "created_at": "2011-09-02T12:00:00Z",
        "body": "sure thing, here's the file",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": [{"id": 1, "display_name": "notes.doc", "uuid": "abcdefabcdefabcdefabcdefabcdef"}]
      },
      {
        "id": 2,
        "created_at": "2011-09-02T11:00:00Z",
        "body": "hey, bob didn't get the notes. do you have a copy i can give him?",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages":
          [
            {
              "id": 1,
              "created_at": "2011-09-02T10:00:00Z",
              "body": "can i get a copy of the notes? i was out",
              "author_id": 3,
              "generated": false,
              "media_comment": null,
              "forwarded_messages": [],
              "attachments": []
            }
          ],
        "attachments": []
      }
    ],
  "submissions": []
}

Edit a conversation ConversationsController#update

PUT /api/v1/conversations/:id

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

Updates attributes for a single conversation.

Request Parameters:

Parameter Type Description
conversation[workflow_state] string

Change the state of this conversation

Allowed values: read, unread, archived

conversation[subscribed] boolean

Toggle the current user’s subscription to the conversation (only valid for group conversations). If unsubscribed, the user will still have access to the latest messages, but the conversation won’t be automatically flagged as unread, nor will it jump to the top of the inbox.

conversation[starred] boolean

Toggle the starred state of the current user’s view of the conversation.

scope string

Used when generating “visible” in the API response. See the explanation under the index API action

Allowed values: unread, starred, archived

filter[] string

Used when generating “visible” in the API response. See the explanation under the index API action

filter_mode string

Used when generating “visible” in the API response. See the explanation under the index API action

Allowed values: and, or, default or

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": ["attachments"],
  "audience": [2],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
  "participants": [{"id": 1, "name": "Joe", "full_name": "Joe TA"}]
}

Mark all as read ConversationsController#mark_all_as_read

POST /api/v1/conversations/mark_all_as_read

Scope: url:POST|/api/v1/conversations/mark_all_as_read

Mark all conversations as read.

Delete a conversation ConversationsController#destroy

DELETE /api/v1/conversations/:id

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

Delete this conversation and its messages. Note that this only deletes this user’s view of the conversation.

Response includes same fields as UPDATE action

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": null,
  "last_message_at": null,
  "message_count": 0,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": []
}

Add recipients ConversationsController#add_recipients

POST /api/v1/conversations/:id/add_recipients

Scope: url:POST|/api/v1/conversations/:id/add_recipients

Add recipients to an existing group conversation. Response is similar to the GET/show action, except that only includes the latest message (e.g. “joe was added to the conversation by bob”)

Request Parameters:

Parameter Type Description
recipients[] Required string

An array of recipient ids. These may be user ids or course/group ids prefixed with “course_” or “group_” respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": "let's talk this over with jim",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": false,
  "starred": null,
  "properties": [],
  "audience": [2, 3, 4],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
  "participants": [
    {"id": 1, "name": "Joe", "full_name": "Joe TA"},
    {"id": 2, "name": "Jane", "full_name": "Jane Teacher"},
    {"id": 3, "name": "Bob", "full_name": "Bob Student"},
    {"id": 4, "name": "Jim", "full_name": "Jim Admin"}
  ],
  "messages":
    [
      {
        "id": 4,
        "created_at": "2011-09-02T12:10:00Z",
        "body": "Jim was added to the conversation by Joe TA",
        "author_id": 1,
        "generated": true,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": []
      }
    ]
}

Add a message ConversationsController#add_message

POST /api/v1/conversations/:id/add_message

Scope: url:POST|/api/v1/conversations/:id/add_message

Add a message to an existing conversation. Response is similar to the GET/show action, except that only includes the latest message (i.e. what we just sent)

An array of user ids. Defaults to all of the current conversation recipients. To explicitly send a message to no other recipients, this array should consist of the logged-in user id.

An array of message ids from this conversation to send to recipients of the new message. Recipients who already had a copy of included messages will not be affected.

Request Parameters:

Parameter Type Description
body Required string

The message to be sent.

attachment_ids[] string

An array of attachments ids. These must be files that have been previously uploaded to the sender’s “conversation attachments” folder.

media_comment_id string

Media comment id of an audio of video file to be associated with this message.

media_comment_type string

Type of the associated media file.

Allowed values: audio, video

recipients[] string

no description

included_messages[] string

no description

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "unread",
  "last_message": "let's talk this over with jim",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": false,
  "starred": null,
  "properties": [],
  "audience": [2, 3],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
  "participants": [
    {"id": 1, "name": "Joe", "full_name": "Joe TA"},
    {"id": 2, "name": "Jane", "full_name": "Jane Teacher"},
    {"id": 3, "name": "Bob", "full_name": "Bob Student"}
  ],
  "messages":
    [
      {
        "id": 3,
        "created_at": "2011-09-02T12:00:00Z",
        "body": "let's talk this over with jim",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": []
      }
    ]
}

Delete a message ConversationsController#remove_messages

POST /api/v1/conversations/:id/remove_messages

Scope: url:POST|/api/v1/conversations/:id/remove_messages

Delete messages from this conversation. Note that this only affects this user’s view of the conversation. If all messages are deleted, the conversation will be as well (equivalent to DELETE)

Request Parameters:

Parameter Type Description
remove[] Required string

Array of message ids to be deleted

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 1,
  "subscribed": true,
  "private": true,
  "starred": null,
  "properties": ["attachments"]
}

Batch update conversations ConversationsController#batch_update

PUT /api/v1/conversations

Scope: url:PUT|/api/v1/conversations

Perform a change on a set of conversations. Operates asynchronously; use the progress endpoint to query the status of an operation.

Request Parameters:

Parameter Type Description
conversation_ids[] Required string

List of conversations to update. Limited to 500 conversations.

event Required string

The action to take on each conversation.

Allowed values: mark_as_read, mark_as_unread, star, unstar, archive, destroy

Example Request:

curl https://<canvas>/api/v1/conversations \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'event=mark_as_read' \
  -d 'conversation_ids[]=1' \
  -d 'conversation_ids[]=2'
Returns a Progress object

Find recipients ConversationsController#find_recipients

GET /api/v1/conversations/find_recipients

Scope: url:GET|/api/v1/conversations/find_recipients

Deprecated, see the Find recipients endpoint in the Search API

Unread count ConversationsController#unread_count

GET /api/v1/conversations/unread_count

Scope: url:GET|/api/v1/conversations/unread_count

Get the number of unread conversations for the current user

Example Response:

{'unread_count': '7'}

Query by course. CourseAuditApiController#for_course

GET /api/v1/audit/course/courses/:course_id

Scope: url:GET|/api/v1/audit/course/courses/:course_id

List course change events for a given course.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of CourseEvent objects

Query by account. CourseAuditApiController#for_account

GET /api/v1/audit/course/accounts/:account_id

Scope: url:GET|/api/v1/audit/course/accounts/:account_id

List course change events for a given account.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of CourseEvent objects

Show a Course pace CoursePacesController#api_show

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

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

Returns a course pace for the course and pace id provided

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the course

course_pace_id Required integer

The id of the course_pace

Example Request:

curl https://<canvas>/api/v1/courses/1/course_pacing/1 \
  -H 'Authorization: Bearer <token>'
Returns a CoursePace object

Create a Course pace CoursePacesController#create

POST /api/v1/courses/:course_id/course_pacing

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

Update a Course pace CoursePacesController#update

PUT /api/v1/courses/:course_id/course_pacing/:id

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

Returns the updated course pace

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the course

course_pace_id Required integer

The id of the course pace

end_date Datetime

End date of the course pace

exclude_weekends boolean

Course pace dates excludes weekends if true

selected_days_to_skip string
Array<String>

Course pace dates excludes weekends if true

hard_end_dates boolean

Course pace uess hard end dates if true

workflow_state string

The state of the course pace

course_pace_module_item_attributes[] string

Module Items attributes

Example Request:

curl https://<canvas>/api/v1/courses/1/course_pacing/1 \
  -X PUT \
  -H 'Authorization: Bearer <token>'
Returns a CoursePace object

Delete a Course pace CoursePacesController#destroy

DELETE /api/v1/courses/:course_id/course_pacing/:id

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

Returns the updated course pace

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the course

course_pace_id Required integer

The id of the course_pace

Example Request:

curl https://<canvas>/api/v1/courses/1/course_pacing/1 \
  -X DELETE \
  -H 'Authorization: Bearer <token>'
Returns a CoursePace object

Set extensions for student quiz submissions Quizzes::CourseQuizExtensionsController#create

POST /api/v1/courses/:course_id/quiz_extensions

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

Responses

  • 200 OK if the request was successful

  • 403 Forbidden if you are not allowed to extend quizzes for this course

Request Parameters:

Parameter Type Description
user_id Required integer

The ID of the user we want to add quiz extensions for.

extra_attempts integer

Number of times the student is allowed to re-take the quiz over the multiple-attempt limit. This is limited to 1000 attempts or less.

extra_time integer

The number of extra minutes to allow for all attempts. This will add to the existing time limit on the submission. This is limited to 10080 minutes (1 week)

manually_unlocked boolean

Allow the student to take the quiz even if it’s locked for everyone else.

extend_from_now integer

The number of minutes to extend the quiz from the current time. This is mutually exclusive to extend_from_end_at. This is limited to 1440 minutes (24 hours)

extend_from_end_at integer

The number of minutes to extend the quiz beyond the quiz’s current ending time. This is mutually exclusive to extend_from_now. This is limited to 1440 minutes (24 hours)

Example Request:

{
  "quiz_extensions": [{
    "user_id": 3,
    "extra_attempts": 2,
    "extra_time": 20,
    "manually_unlocked": true
  },{
    "user_id": 2,
    "extra_attempts": 2,
    "extra_time": 20,
    "manually_unlocked": false
  }]
}

{
  "quiz_extensions": [{
    "user_id": 3,
    "extend_from_now": 20
  }]
}

Example Response:

{
  "quiz_extensions": [QuizExtension]
}

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’

  • “grading_periods”: Optional information to include with each Course. When grading_periods is given, a list of the grading periods associated with each course is returned.

  • “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 information to include with each Course. Returns course image url if a course image has been set.

  • “banner_image”: Optional information to include with each Course. Returns course banner image url if the course is a Canvas for Elementary subject and a banner image has been set.

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

  • “post_manually”: Optional information to include with each Course. Returns true if the course post policy is set to Manually post grades. Returns false if the the course post policy is set to Automatically post grades.

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

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 Course objects

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.

  • “grading_periods”: Optional information to include with each Course. When grading_periods is given, a list of the grading periods associated with each course is returned.

  • “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 information to include with each Course. Returns course image url if a course image has been set.

  • “banner_image”: Optional information to include with each Course. Returns course banner image url if the course is a Canvas for Elementary subject and a banner image has been set.

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

  • “post_manually”: Optional information to include with each Course. Returns true if the course post policy is set to “Manually”. Returns false if the the course post policy is set to “Automatically”.

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

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

homeroom boolean

If set, only return homeroom courses.

account_id string

If set, only include courses associated with this account

Returns a list of Course objects

Get user progress CoursesController#user_progress

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

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

Return progress information for the user and course

You can supply self as the user_id to query your own progress in a course. To query another user’s progress, you must be a teacher in the course, an administrator, or a linked observer of the user.

Returns a CourseProgress object

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 This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true.

course[end_at] DateTime

Course end date in ISO8601 format. e.g. 2011-01-01T01:00Z This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true.

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. This value must be set to true in order to specify a course start date and/or end date.

course[term_id] string

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

course[post_manually] boolean

Default is false. When true, all grades in the course must be posted manually, and will not be automatically posted. When false, all grades in the course will be automatically posted.

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 object

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 User objects

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 User objects

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 User objects

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 an User object

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 User objects

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,
  "hide_sections_on_course_users_page": false,
  "lock_all_announcements": true,
  "usage_rights_required": false,
  "homeroom_course": false,
  "default_due_time": "23:59:59",
  "conditional_release": 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_final_grade_override boolean

Let student final grades for a grading period or the total grades for the course be overridden

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 replies

allow_student_organized_groups boolean

Let students organize their own groups

allow_student_discussion_reporting boolean

Let students report offensive discussion content

allow_student_anonymous_discussion_topics boolean

Let students create anonymous discussion topics

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

hide_sections_on_course_users_page boolean

Disallow students from viewing students in sections they do not belong to

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). Canvas for Elementary subjects ignore this setting.

home_page_announcement_limit integer

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

syllabus_course_summary boolean

Show the course summary (list of assignments and calendar events) on the syllabus page. Default is true.

default_due_time string

Set the default due time for assignments. This is the time that will be pre-selected in the Canvas user interface when setting a due date for an assignment. It does not change when any existing assignment is due. It should be given in 24-hour HH:MM:SS format. The default is “23:59:59”. Use “inherit” to inherit the account setting.

conditional_release boolean

Enable or disable individual learning paths for students based on assessment

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 an User object

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”: Include course image url if a course image has been set

  • “banner_image”: Include course banner image url if the course is a Canvas for Elementary subject and a banner image has been set

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

  • “lti_context_id”: Include course LTI tool id.

  • “post_manually”: Include course post policy. If the post policy is manually post grades, the value will be true. If the post policy is automatically post grades, the value will be false.

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, course_image, banner_image, concluded, lti_context_id, post_manually

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 object

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”

If an account has set prevent_course_availability_editing_by_teachers, a teacher cannot change course, course, or course here.

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 This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true, or the course is already published.

course[end_at] DateTime

Course end date in ISO8601 format. e.g. 2011-01-01T01:00Z This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true.

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. Setting this value to false will remove the course end date (if it exists), as well as the course start date (if the course is unpublished).

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

If this option is set to true, the course banner image url and course banner 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
course[homeroom_course] boolean

Sets the course as a homeroom course. The setting takes effect only when the course is associated with a Canvas for Elementary-enabled account.

course[sync_enrollments_from_homeroom] string

Syncs enrollments from the homeroom that is set in homeroom_course_id. The setting only takes effect when the course is associated with a Canvas for Elementary-enabled account and sync_enrollments_from_homeroom is enabled.

course[homeroom_course_id] string

Sets the Homeroom Course id to be used with sync_enrollments_from_homeroom. The setting only takes effect when the course is associated with a Canvas for Elementary-enabled account and sync_enrollments_from_homeroom is enabled.

course[template] boolean

Enable or disable the course as a template that can be selected by an account

course[course_color] string

Sets a color in hex code format to be associated with the course. The setting takes effect only when the course is associated with a Canvas for Elementary-enabled account.

course[friendly_name] string

Set a friendly name for the course. If this is provided and the course is associated with a Canvas for Elementary account, it will be shown instead of the course name. This setting takes priority over course nicknames defined by individual users.

course[enable_course_paces] boolean

Enable or disable Course Pacing for the course. This setting only has an effect when the Course Pacing feature flag is enabled for the sub-account. Otherwise, Course Pacing are always disabled.

Note: Course Pacing is in active development.
course[conditional_release] boolean

Enable or disable individual learning paths for students based on assessment

course[post_manually] boolean

When true, all grades in the course will be posted manually. When false, all grades in the course will be automatically posted. Use with caution as this setting will override any assignment level post policy.

override_sis_stickiness boolean

Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness

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.

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

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.

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 object

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 object

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 bulk user progress CoursesController#bulk_user_progress

GET /api/v1/courses/:course_id/bulk_user_progress

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

Returns progress information for all users enrolled in the given course.

You must be a user who has permission to view all grades in the course (such as a teacher or administrator).

Example Request:

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

Example Response:

[
  {
    "id": 1,
    "display_name": "Test Student 1",
    "avatar_image_url": "https://<canvas>/images/messages/avatar-50.png",
    "html_url": "https://<canvas>/courses/1/users/1",
    "pronouns": null,
    "progress": {
      "requirement_count": 2,
      "requirement_completed_count": 1,
      "next_requirement_url": "https://<canvas>/courses/<course_id>/modules/items/<item_id>",
      "completed_at": null
    }
  },
  {
    "id": 2,
    "display_name": "Test Student 2",
    "avatar_image_url": "https://<canvas>/images/messages/avatar-50.png",
    "html_url": "https://<canvas>/courses/1/users/2",
    "pronouns": null,
    "progress": {
      "requirement_count": 2,
      "requirement_completed_count": 2,
      "next_requirement_url": null,
      "completed_at": "2021-08-10T16:26:08Z"
    }
  }
]

Remove quiz migration alert CoursesController#dismiss_migration_limitation_msg

POST /api/v1/courses/:id/dismiss_migration_limitation_message

Scope: url:POST|/api/v1/courses/:id/dismiss_migration_limitation_message

Remove alert about the limitations of quiz migrations that is displayed to a user in a course

you must be logged in to use this endpoint

Example Response:

{ "success": "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

List custom gradebook columns CustomGradebookColumnsApiController#index

GET /api/v1/courses/:course_id/custom_gradebook_columns

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

A paginated list of all custom gradebook columns for a course

Request Parameters:

Parameter Type Description
include_hidden boolean

Include hidden parameters (defaults to false)

Returns a list of CustomColumn objects

Create a custom gradebook column CustomGradebookColumnsApiController#create

POST /api/v1/courses/:course_id/custom_gradebook_columns

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

Create a custom gradebook column

Request Parameters:

Parameter Type Description
column[title] Required string

no description

column[position] integer

The position of the column relative to other custom columns

column[hidden] boolean

Hidden columns are not displayed in the gradebook

column[teacher_notes] boolean

Set this if the column is created by a teacher. The gradebook only supports one teacher_notes column.

column[read_only] boolean

Set this to prevent the column from being editable in the gradebook ui

Returns a CustomColumn object

Update a custom gradebook column CustomGradebookColumnsApiController#update

PUT /api/v1/courses/:course_id/custom_gradebook_columns/:id

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

Accepts the same parameters as custom gradebook column creation

Returns a CustomColumn object

Delete a custom gradebook column CustomGradebookColumnsApiController#destroy

DELETE /api/v1/courses/:course_id/custom_gradebook_columns/:id

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

Permanently deletes a custom column and its associated data

Returns a CustomColumn object

Reorder custom columns CustomGradebookColumnsApiController#reorder

POST /api/v1/courses/:course_id/custom_gradebook_columns/reorder

Scope: url:POST|/api/v1/courses/:course_id/custom_gradebook_columns/reorder

Puts the given columns in the specified order

200 OK is returned if successful

Request Parameters:

Parameter Type Description
order[] Required integer

no description

List entries for a column CustomGradebookColumnDataApiController#index

GET /api/v1/courses/:course_id/custom_gradebook_columns/:id/data

Scope: url:GET|/api/v1/courses/:course_id/custom_gradebook_columns/:id/data

This does not list entries for students without associated data.

Request Parameters:

Parameter Type Description
include_hidden boolean

If true, hidden columns will be included in the result. If false or absent, only visible columns will be returned.

Returns a list of ColumnDatum objects

Update column data CustomGradebookColumnDataApiController#update

PUT /api/v1/courses/:course_id/custom_gradebook_columns/:id/data/:user_id

Scope: url:PUT|/api/v1/courses/:course_id/custom_gradebook_columns/:id/data/:user_id

Set the content of a custom column

Request Parameters:

Parameter Type Description
column_data[content] Required string

Column content. Setting this to blank will delete the datum object.

Returns a ColumnDatum object

Bulk update column data CustomGradebookColumnDataApiController#bulk_update

PUT /api/v1/courses/:course_id/custom_gradebook_column_data

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

Set the content of custom columns

{

"column_data": [
  {
    "column_id": example_column_id,
    "user_id": example_student_id,
    "content": example_content
    },
    {
    "column_id": example_column_id,
    "user_id": example_student_id,
    "content: example_content
  }
]

}

Request Parameters:

Parameter Type Description
column_data[] Required Array

Column content. Setting this to an empty string will delete the data object.

Example Request:

Returns a Progress object

Create a Developer Key Account Binding DeveloperKeyAccountBindingsController#create_or_update

POST /api/v1/accounts/:account_id/developer_keys/:developer_key_id/developer_key_account_bindings

Scope: url:POST|/api/v1/accounts/:account_id/developer_keys/:developer_key_id/developer_key_account_bindings

Create a new Developer Key Account Binding. The developer key specified in the request URL must be available in the requested account or the requeted account’s account chain. If the binding already exists for the specified account/key combination it will be updated.

Request Parameters:

Parameter Type Description
workflow_state string

The workflow state for the binding. Must be one of “on”, “off”, or “allow”. Defaults to “off”.

Returns a DeveloperKeyAccountBinding object

List Developer Keys DeveloperKeysController#index

GET /api/v1/accounts/:account_id/developer_keys

Scope: url:GET|/api/v1/accounts/:account_id/developer_keys

List all developer keys created in the current account.

Request Parameters:

Parameter Type Description
inherited boolean

Defaults to false. If true, lists keys inherited from Site Admin (and consortium parent account, if applicable).

Returns a list of DeveloperKey objects

Create a Developer Key DeveloperKeysController#create

POST /api/v1/accounts/:account_id/developer_keys

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

Create a new Canvas API key. Creating an LTI 1.3 registration is not supported here and should be done via the LTI Registration API.

Request Parameters:

Parameter Type Description
developer_key Required json

no description

developer_key[auto_expire_tokens] boolean

Defaults to false. If true, access tokens generated by this key will expire after 1 hour.

developer_key[email] string

Contact email for the key.

developer_key[icon_url] string

URL for a small icon to display in key list.

developer_key[name] string

The display name.

developer_key[notes] string

User-provided notes about the key.

developer_key[redirect_uri] string

Deprecated in favor of redirect_uris. Do not use.

developer_key[redirect_uris] array

List of URLs used during OAuth2 flow to validate given redirect URI.

developer_key[vendor_code] string

User-specified code representing the vendor that uses the key.

developer_key[visible] boolean

Defaults to true. If false, key will not be visible in the UI.

developer_key[test_cluster_only] boolean

Defaults to false. If true, key is only usable in non-production environments (test, beta). Avoids problems with beta refresh.

developer_key[client_credentials_audience] string

Used in OAuth2 client credentials flow to specify the audience for the access token.

developer_key[scopes] array

List of API endpoints key is allowed to access.

developer_key[require_scopes] boolean

If true, then token requests with this key must include scopes.

developer_key[allow_includes] boolean

If true, allows ‘includes` parameters in API requests that match the scopes of this key.

Returns a DeveloperKey object

Update a Developer Key DeveloperKeysController#update

PUT /api/v1/developer_keys/:id

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

Update an existing Canvas API key. Updating an LTI 1.3 registration is not supported here and should be done via the LTI Registration API.

Request Parameters:

Parameter Type Description
developer_key Required json

no description

developer_key[auto_expire_tokens] boolean

Defaults to false. If true, access tokens generated by this key will expire after 1 hour.

developer_key[email] string

Contact email for the key.

developer_key[icon_url] string

URL for a small icon to display in key list.

developer_key[name] string

The display name.

developer_key[notes] string

User-provided notes about the key.

developer_key[redirect_uri] string

Deprecated in favor of redirect_uris. Do not use.

developer_key[redirect_uris] array

List of URLs used during OAuth2 flow to validate given redirect URI.

developer_key[vendor_code] string

User-specified code representing the vendor that uses the key.

developer_key[visible] boolean

Defaults to true. If false, key will not be visible in the UI.

developer_key[test_cluster_only] boolean

Defaults to false. If true, key is only usable in non-production environments (test, beta). Avoids problems with beta refresh.

developer_key[client_credentials_audience] string

Used in OAuth2 client credentials flow to specify the audience for the access token.

developer_key[scopes] array

List of API endpoints key is allowed to access.

developer_key[require_scopes] boolean

If true, then token requests with this key must include scopes.

developer_key[allow_includes] boolean

If true, allows ‘includes` parameters in API requests that match the scopes of this key.

Returns a DeveloperKey object

Delete a Developer Key DeveloperKeysController#destroy

DELETE /api/v1/developer_keys/:id

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

Delete an existing Canvas API key. Deleting an LTI 1.3 registration should be done via the LTI Registration API.

Returns a DeveloperKey object

List discussion topics DiscussionTopicsController#index

GET /api/v1/courses/:course_id/discussion_topics

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

GET /api/v1/groups/:group_id/discussion_topics

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics

Returns the paginated list of discussion topics for this course or group.

Request Parameters:

Parameter Type Description
include[] string

If “all_dates” is passed, all dates associated with graded discussions’ assignments will be included. if “sections” is passed, includes the course sections that are associated with the topic, if the topic is specific to certain sections of the course. If “sections_user_count” is passed, then:

(a) If sections were asked for *and* the topic is specific to certain
    course sections, includes the number of users in each
    section. (as part of the section json asked for above)
(b) Else, includes at the root level the total number of users in the
    topic's context (group or course) that the topic applies to.

If “overrides” is passed, the overrides for the assignment will be included

Allowed values: all_dates, sections, sections_user_count, overrides

order_by string

Determines the order of the discussion topic list. Defaults to “position”.

Allowed values: position, recent_activity, title

scope string

Only return discussion topics in the given state(s). Defaults to including all topics. Filtering is done after pagination, so pages may be smaller than requested if topics are filtered. Can pass multiple states as comma separated string.

Allowed values: locked, unlocked, pinned, unpinned

only_announcements boolean

Return announcements instead of discussion topics. Defaults to false

filter_by string

The state of the discussion topic to return. Currently only supports unread state.

Allowed values: all, unread

search_term string

The partial title of the discussion topics to match and return.

exclude_context_module_locked_topics boolean

For students, exclude topics that are locked by module progression. Defaults to false.

Example Request:

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

Create a new discussion topic DiscussionTopicsController#create

POST /api/v1/courses/:course_id/discussion_topics

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

POST /api/v1/groups/:group_id/discussion_topics

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics

Create an new discussion topic for the course or group.

Request Parameters:

Parameter Type Description
title string

no description

message string

no description

discussion_type string

The type of discussion. Defaults to side_comment or not_threaded if not value is given. Accepted values are ‘side_comment’, ‘not_threaded’ for discussions that only allow one level of nested comments, and ‘threaded’ for fully threaded discussions.

Allowed values: side_comment, threaded, not_threaded

published boolean

Whether this topic is published (true) or draft state (false). Only teachers and TAs have the ability to create draft state topics.

delayed_post_at DateTime

If a timestamp is given, the topic will not be published until that time.

allow_rating boolean

Whether or not users can rate entries in this topic.

lock_at DateTime

If a timestamp is given, the topic will be scheduled to lock at the provided timestamp. If the timestamp is in the past, the topic will be locked.

podcast_enabled boolean

If true, the topic will have an associated podcast feed.

podcast_has_student_posts boolean

If true, the podcast will include posts from students as well. Implies podcast_enabled.

require_initial_post boolean

If true then a user may not respond to other replies until that user has made an initial reply. Defaults to false.

assignment Assignment

To create an assignment discussion, pass the assignment parameters as a sub-object. See the Create an Assignment API for the available parameters. The name parameter will be ignored, as it’s taken from the discussion title. If you want to make a discussion that was an assignment NOT an assignment, pass set_assignment = false as part of the assignment object

is_announcement boolean

If true, this topic is an announcement. It will appear in the announcement’s section rather than the discussions section. This requires announcment-posting permissions.

pinned boolean

If true, this topic will be listed in the “Pinned Discussion” section

position_after string

By default, discussions are sorted chronologically by creation date, you can pass the id of another topic to have this one show up after the other when they are listed.

group_category_id integer

If present, the topic will become a group discussion assigned to the group.

only_graders_can_rate boolean

If true, only graders will be allowed to rate entries.

sort_by_rating boolean

If true, entries will be sorted by rating.

attachment File

A multipart/form-data form-field-style attachment. Attachments larger than 1 kilobyte are subject to quota restrictions.

specific_sections string

A comma-separated list of sections ids to which the discussion topic should be made specific to. If it is not desired to make the discussion topic specific to sections, then this parameter may be omitted or set to “all”. Can only be present only on announcements and only those that are for a course (as opposed to a group).

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics \
    -F title='my topic' \
    -F message='initial message' \
    -F podcast_enabled=1 \
    -H 'Authorization: Bearer <token>'
    -F 'attachment=@<filename>' \

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics \
    -F title='my assignment topic' \
    -F message='initial message' \
    -F assignment[points_possible]=15 \
    -H 'Authorization: Bearer <token>'

Update a topic DiscussionTopicsController#update

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id

Update an existing discussion topic for the course or group.

Request Parameters:

Parameter Type Description
title string

no description

message string

no description

discussion_type string

The type of discussion. Defaults to side_comment or not_threaded if not value is given. Accepted values are ‘side_comment’, ‘not_threaded’ for discussions that only allow one level of nested comments, and ‘threaded’ for fully threaded discussions.

Allowed values: side_comment, threaded, not_threaded

published boolean

Whether this topic is published (true) or draft state (false). Only teachers and TAs have the ability to create draft state topics.

delayed_post_at DateTime

If a timestamp is given, the topic will not be published until that time.

lock_at DateTime

If a timestamp is given, the topic will be scheduled to lock at the provided timestamp. If the timestamp is in the past, the topic will be locked.

podcast_enabled boolean

If true, the topic will have an associated podcast feed.

podcast_has_student_posts boolean

If true, the podcast will include posts from students as well. Implies podcast_enabled.

require_initial_post boolean

If true then a user may not respond to other replies until that user has made an initial reply. Defaults to false.

assignment Assignment

To create an assignment discussion, pass the assignment parameters as a sub-object. See the Create an Assignment API for the available parameters. The name parameter will be ignored, as it’s taken from the discussion title. If you want to make a discussion that was an assignment NOT an assignment, pass set_assignment = false as part of the assignment object

is_announcement boolean

If true, this topic is an announcement. It will appear in the announcement’s section rather than the discussions section. This requires announcment-posting permissions.

pinned boolean

If true, this topic will be listed in the “Pinned Discussion” section

position_after string

By default, discussions are sorted chronologically by creation date, you can pass the id of another topic to have this one show up after the other when they are listed.

group_category_id integer

If present, the topic will become a group discussion assigned to the group.

allow_rating boolean

If true, users will be allowed to rate entries.

only_graders_can_rate boolean

If true, only graders will be allowed to rate entries.

sort_by_rating boolean

If true, entries will be sorted by rating.

specific_sections string

A comma-separated list of sections ids to which the discussion topic should be made specific too. If it is not desired to make the discussion topic specific to sections, then this parameter may be omitted or set to “all”. Can only be present only on announcements and only those that are for a course (as opposed to a group).

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id> \
    -F title='This will be positioned after Topic #1234' \
    -F position_after=1234 \
    -H 'Authorization: Bearer <token>'

Delete a topic DiscussionTopicsController#destroy

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id

Scope: url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id

Scope: url:DELETE|/api/v1/groups/:group_id/discussion_topics/:topic_id

Deletes the discussion topic. This will also delete the assignment, if it’s an assignment discussion.

Example Request:

curl -X DELETE https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id> \
     -H 'Authorization: Bearer <token>'

Reorder pinned topics DiscussionTopicsController#reorder

POST /api/v1/courses/:course_id/discussion_topics/reorder

Scope: url:POST|/api/v1/courses/:course_id/discussion_topics/reorder

POST /api/v1/groups/:group_id/discussion_topics/reorder

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics/reorder

Puts the pinned discussion topics in the specified order. All pinned topics should be included.

Request Parameters:

Parameter Type Description
order[] Required integer

The ids of the pinned discussion topics in the desired order. (For example, “order=104,102,103”.)

Update an entry DiscussionEntriesController#update

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:id

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:id

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:id

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:id

Update an existing discussion entry.

The entry must have been created by the current user, or the current user must have admin rights to the discussion. If the edit is not allowed, a 401 will be returned.

Request Parameters:

Parameter Type Description
message string

The updated body of the entry.

Example Request:

curl -X PUT 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>' \
     -F 'message=<message>' \
     -H "Authorization: Bearer <token>"

Delete an entry DiscussionEntriesController#destroy

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:id

Scope: url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:id

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:id

Scope: url:DELETE|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:id

Delete a discussion entry.

The entry must have been created by the current user, or the current user must have admin rights to the discussion. If the delete is not allowed, a 401 will be returned.

The discussion will be marked deleted, and the user_id and message will be cleared out.

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>' \
     -H "Authorization: Bearer <token>"

Get a single topic DiscussionTopicsApiController#show

GET /api/v1/courses/:course_id/discussion_topics/:topic_id

Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id

GET /api/v1/groups/:group_id/discussion_topics/:topic_id

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics/:topic_id

Returns data on an individual discussion topic. See the List action for the response formatting.

Request Parameters:

Parameter Type Description
include[] string

If “all_dates” is passed, all dates associated with graded discussions’ assignments will be included. if “sections” is passed, includes the course sections that are associated with the topic, if the topic is specific to certain sections of the course. If “sections_user_count” is passed, then:

(a) If sections were asked for *and* the topic is specific to certain
    course sections, includes the number of users in each
    section. (as part of the section json asked for above)
(b) Else, includes at the root level the total number of users in the
    topic's context (group or course) that the topic applies to.

If “overrides” is passed, the overrides for the assignment will be included

Allowed values: all_dates, sections, sections_user_count, overrides

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id> \
    -H 'Authorization: Bearer <token>'

Summary DiscussionTopicsApiController#summary

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/summaries

Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/summaries

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/summaries

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics/:topic_id/summaries

Generates a summary for a discussion topic.

Request Parameters:

Parameter Type Description
userInput string

Areas or topics for the summary to focus on.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/summaries \
    -H 'Authorization: Bearer <token>'

Example Response:

{
  "id": 1,
  "text": "This is a summary of the discussion topic."
}

Disable summary DiscussionTopicsApiController#disable_summary

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/summaries/disable

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/summaries/disable

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/summaries/disable

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id/summaries/disable

Disables the summary for a discussion topic.

Example Request:

curl -X PUT https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/disable_summary \

Example Response:

{
  "success": true
}

Summary Feedback DiscussionTopicsApiController#summary_feedback

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/summaries/:summary_id/feedback

Scope: url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/summaries/:summary_id/feedback

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/summaries/:summary_id/feedback

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics/:topic_id/summaries/:summary_id/feedback

Persists feedback on a discussion topic summary.

Request Parameters:

Parameter Type Description
_action string

Required The action to take on the summary. Possible values are:

  • “seen”: Marks the summary as seen. This action saves the feedback if it’s not already persisted.

  • “like”: Marks the summary as liked.

  • “dislike”: Marks the summary as disliked.

  • “reset_like”: Resets the like status of the summary.

  • “regenerate”: Regenerates the summary feedback.

  • “disable_summary”: Disables the summary feedback.

Any other value will result in an error response.

Example Request:

curl -X POST https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/summaries/<summary_id>/feedback \
     -F '_action=like' \
     -H "Authorization: Bearer

Example Response:

{
  "liked": true,
  "disliked": false
}

Get the full topic DiscussionTopicsApiController#view

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/view

Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/view

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/view

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics/:topic_id/view

Return a cached structure of the discussion topic, containing all entries, their authors, and their message bodies.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.

In some rare situations, this cached structure may not be available yet. In that case, the server will respond with a 503 error, and the caller should try again soon.

The response is an object containing the following keys:

  • “participants”: A list of summary information on users who have posted to the discussion. Each value is an object containing their id, display_name, and avatar_url.

  • “unread_entries”: A list of entry ids that are unread by the current user. this implies that any entry not in this list is read.

  • “entry_ratings”: A map of entry ids to ratings by the current user. Entries not in this list have no rating. Only populated if rating is enabled.

  • “forced_entries”: A list of entry ids that have forced_read_state set to true. This flag is meant to indicate the entry’s read_state has been manually set to ‘unread’ by the user, so the entry should not be automatically marked as read.

  • “view”: A threaded view of all the entries in the discussion, containing the id, user_id, and message.

  • “new_entries”: Because this view is eventually consistent, it’s possible that newly created or updated entries won’t yet be reflected in the view. If the application wants to also get a flat list of all entries not yet reflected in the view, pass include_new_entries=1 to the request and this array of entries will be returned. These entries are returned in a flat array, in ascending created_at order.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/view' \
     -H "Authorization: Bearer <token>"

Example Response:

{
  "unread_entries": [1,3,4],
  "entry_ratings": {3: 1},
  "forced_entries": [1],
  "participants": [
    { "id": 10, "display_name": "user 1", "avatar_image_url": "https://...", "html_url": "https://..." },
    { "id": 11, "display_name": "user 2", "avatar_image_url": "https://...", "html_url": "https://..." }
  ],
  "view": [
    { "id": 1, "user_id": 10, "parent_id": null, "message": "...html text...", "replies": [
      { "id": 3, "user_id": 11, "parent_id": 1, "message": "...html....", "replies": [...] }
    ]},
    { "id": 2, "user_id": 11, "parent_id": null, "message": "...html..." },
    { "id": 4, "user_id": 10, "parent_id": null, "message": "...html..." }
  ]
}

Post an entry DiscussionTopicsApiController#add_entry

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries

Scope: url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/entries

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries

Create a new entry in a discussion topic. Returns a json representation of the created entry (see documentation for ‘entries’ method) on success.

Request Parameters:

Parameter Type Description
message string

The body of the entry.

attachment string

a multipart/form-data form-field-style attachment. Attachments larger than 1 kilobyte are subject to quota restrictions.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries.json' \
     -F 'message=<message>' \
     -F 'attachment=@<filename>' \
     -H "Authorization: Bearer <token>"

Duplicate discussion topic DiscussionTopicsApiController#duplicate

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/duplicate

Scope: url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/duplicate

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/duplicate

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics/:topic_id/duplicate

Duplicate a discussion topic according to context (Course/Group)

Example Request:

curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/discussion_topics/123/duplicate

curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/group/456/discussion_topics/456/duplicate
Returns a DiscussionTopic object

List topic entries DiscussionTopicsApiController#entries

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entries

Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entries

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries

Retrieve the (paginated) top-level entries in a discussion topic.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.

Will include the 10 most recent replies, if any, for each entry returned.

If the topic is a root topic with children corresponding to groups of a group assignment, entries from those subtopics for which the user belongs to the corresponding group will be returned.

Ordering of returned entries is newest-first by posting timestamp (reply activity is ignored).

API response field:

  • id

    The unique identifier for the entry.

  • user_id

    The unique identifier for the author of the entry.

  • editor_id

    The unique user id of the person to last edit the entry, if different than user_id.

  • user_name

    The name of the author of the entry.

  • message

    The content of the entry.

  • read_state

    The read state of the entry, “read” or “unread”.

  • forced_read_state

    Whether the read_state was forced (was set manually)

  • created_at

    The creation time of the entry, in ISO8601 format.

  • updated_at

    The updated time of the entry, in ISO8601 format.

  • attachment

    JSON representation of the attachment for the entry, if any. Present only if there is an attachment.

  • attachments

    Deprecated. Same as attachment, but returned as a one-element array. Present only if there is an attachment.

  • recent_replies

    The 10 most recent replies for the entry, newest first. Present only if there is at least one reply.

  • has_more_replies

    True if there are more than 10 replies for the entry (i.e., not all were included in this response). Present only if there is at least one reply.

Example Response:

[ {
    "id": 1019,
    "user_id": 7086,
    "user_name": "nobody@example.com",
    "message": "Newer entry",
    "read_state": "read",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:33:29Z",
    "attachment": {
      "content-type": "unknown/unknown",
      "url": "http://www.example.com/files/681/download?verifier=JDG10Ruitv8o6LjGXWlxgOb5Sl3ElzVYm9cBKUT3",
      "filename": "content.txt",
      "display_name": "content.txt" } },
  {
    "id": 1016,
    "user_id": 7086,
    "user_name": "nobody@example.com",
    "message": "first top-level entry",
    "read_state": "unread",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:32:29Z",
    "recent_replies": [
      {
        "id": 1017,
        "user_id": 7086,
        "user_name": "nobody@example.com",
        "message": "Reply message",
        "created_at": "2011-11-03T21:32:29Z"
      } ],
    "has_more_replies": false } ]

Post a reply DiscussionTopicsApiController#add_reply

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies

Scope: url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/replies

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/replies

Add a reply to an entry in a discussion topic. Returns a json representation of the created reply (see documentation for ‘replies’ method) on success.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.

Request Parameters:

Parameter Type Description
message string

The body of the entry.

attachment string

a multipart/form-data form-field-style attachment. Attachments larger than 1 kilobyte are subject to quota restrictions.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/replies.json' \
     -F 'message=<message>' \
     -F 'attachment=@<filename>' \
     -H "Authorization: Bearer <token>"

List entry replies DiscussionTopicsApiController#replies

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies

Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/replies

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/replies

Retrieve the (paginated) replies to a top-level entry in a discussion topic.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.

Ordering of returned entries is newest-first by creation timestamp.

API response field:

  • id

    The unique identifier for the reply.

  • user_id

    The unique identifier for the author of the reply.

  • editor_id

    The unique user id of the person to last edit the entry, if different than user_id.

  • user_name

    The name of the author of the reply.

  • message

    The content of the reply.

  • read_state

    The read state of the entry, “read” or “unread”.

  • forced_read_state

    Whether the read_state was forced (was set manually)

  • created_at

    The creation time of the reply, in ISO8601 format.

Example Response:

[ {
    "id": 1015,
    "user_id": 7084,
    "user_name": "nobody@example.com",
    "message": "Newer message",
    "read_state": "read",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:27:44Z" },
  {
    "id": 1014,
    "user_id": 7084,
    "user_name": "nobody@example.com",
    "message": "Older message",
    "read_state": "unread",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:26:44Z" } ]

List entries DiscussionTopicsApiController#entry_list

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entry_list

Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/entry_list

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entry_list

Scope: url:GET|/api/v1/groups/:group_id/discussion_topics/:topic_id/entry_list

Retrieve a paginated list of discussion entries, given a list of ids.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.

Request Parameters:

Parameter Type Description
ids[] string

A list of entry ids to retrieve. Entries will be returned in id order, smallest id first.

API response field:

  • id

    The unique identifier for the reply.

  • user_id

    The unique identifier for the author of the reply.

  • user_name

    The name of the author of the reply.

  • message

    The content of the reply.

  • read_state

    The read state of the entry, “read” or “unread”.

  • forced_read_state

    Whether the read_state was forced (was set manually)

  • created_at

    The creation time of the reply, in ISO8601 format.

  • deleted

    If the entry has been deleted, returns true. The user_id, user_name, and message will not be returned for deleted entries.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entry_list?ids[]=1&ids[]=2&ids[]=3' \
     -H "Authorization: Bearer <token>"

Example Response:

[
  { ... entry 1 ... },
  { ... entry 2 ... },
  { ... entry 3 ... },
]

Mark topic as read DiscussionTopicsApiController#mark_topic_read

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/read

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/read

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/read

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id/read

Mark the initial text of the discussion topic as read.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read.json' \
     -X PUT \
     -H "Authorization: Bearer <token>" \
     -H "Content-Length: 0"

Mark all topic as read DiscussionTopicsApiController#mark_all_topic_read

PUT /api/v1/courses/:course_id/discussion_topics/read_all

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/read_all

PUT /api/v1/groups/:group_id/discussion_topics/read_all

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/read_all

Mark the initial text of all the discussion topics as read in the context.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/read_all' \
     -X POST \
     -H "Authorization: Bearer <token>" \
     -H "Content-Length: 0"

Mark topic as unread DiscussionTopicsApiController#mark_topic_unread

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/read

Scope: url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/read

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/read

Scope: url:DELETE|/api/v1/groups/:group_id/discussion_topics/:topic_id/read

Mark the initial text of the discussion topic as unread.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read.json' \
     -X DELETE \
     -H "Authorization: Bearer <token>"

Mark all entries as read DiscussionTopicsApiController#mark_all_read

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/read_all

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/read_all

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/read_all

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id/read_all

Mark the discussion topic and all its entries as read.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

Parameter Type Description
forced_read_state boolean

A boolean value to set all of the entries’ forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read_all.json' \
     -X PUT \
     -H "Authorization: Bearer <token>" \
     -H "Content-Length: 0"

Mark all entries as unread DiscussionTopicsApiController#mark_all_unread

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/read_all

Scope: url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/read_all

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/read_all

Scope: url:DELETE|/api/v1/groups/:group_id/discussion_topics/:topic_id/read_all

Mark the discussion topic and all its entries as unread.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

Parameter Type Description
forced_read_state boolean

A boolean value to set all of the entries’ forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read_all.json' \
     -X DELETE \
     -H "Authorization: Bearer <token>"

Mark entry as read DiscussionTopicsApiController#mark_entry_read

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/read

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/read

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/read

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/read

Mark a discussion entry as read.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

Parameter Type Description
forced_read_state boolean

A boolean value to set the entry’s forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/read.json' \
     -X PUT \
     -H "Authorization: Bearer <token>"\
     -H "Content-Length: 0"

Mark entry as unread DiscussionTopicsApiController#mark_entry_unread

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/read

Scope: url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/read

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/read

Scope: url:DELETE|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/read

Mark a discussion entry as unread.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

Parameter Type Description
forced_read_state boolean

A boolean value to set the entry’s forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/read.json' \
     -X DELETE \
     -H "Authorization: Bearer <token>"

Rate entry DiscussionTopicsApiController#rate_entry

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/rating

Scope: url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/rating

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/rating

Scope: url:POST|/api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/rating

Rate a discussion entry.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

Parameter Type Description
rating integer

A rating to set on this entry. Only 0 and 1 are accepted.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/rating.json' \
     -X POST \
     -H "Authorization: Bearer <token>"

Subscribe to a topic DiscussionTopicsApiController#subscribe_topic

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed

Scope: url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed

Scope: url:PUT|/api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed

Subscribe to a topic to receive notifications about new entries

On success, the response will be 204 No Content with an empty body

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/subscribed.json' \
     -X PUT \
     -H "Authorization: Bearer <token>" \
     -H "Content-Length: 0"

Unsubscribe from a topic DiscussionTopicsApiController#unsubscribe_topic

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed

Scope: url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed

Scope: url:DELETE|/api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed

Unsubscribe from a topic to stop receiving notifications about new entries

On success, the response will be 204 No Content with an empty body

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/subscribed.json' \
     -X DELETE \
     -H "Authorization: Bearer <token>"

Create enrollment term TermsController#create

POST /api/v1/accounts/:account_id/terms

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

Create a new enrollment term for the specified account.

Request Parameters:

Parameter Type Description
enrollment_term[name] string

The name of the term.

enrollment_term[start_at] DateTime

The day/time the term starts. Accepts times in ISO 8601 format, e.g. 2015-01-10T18:48:00Z.

enrollment_term[end_at] DateTime

The day/time the term ends. Accepts times in ISO 8601 format, e.g. 2015-01-10T18:48:00Z.

enrollment_term[sis_term_id] string

The unique SIS identifier for the term.

enrollment_term[overrides][enrollment_type][start_at] DateTime

The day/time the term starts, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment

enrollment_term[overrides][enrollment_type][end_at] DateTime

The day/time the term ends, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment

Returns an EnrollmentTerm object

Update enrollment term TermsController#update

PUT /api/v1/accounts/:account_id/terms/:id

Scope: url:PUT|/api/v1/accounts/:account_id/terms/:id

Update an existing enrollment term for the specified account.

Request Parameters:

Parameter Type Description
enrollment_term[name] string

The name of the term.

enrollment_term[start_at] DateTime

The day/time the term starts. Accepts times in ISO 8601 format, e.g. 2015-01-10T18:48:00Z.

enrollment_term[end_at] DateTime

The day/time the term ends. Accepts times in ISO 8601 format, e.g. 2015-01-10T18:48:00Z.

enrollment_term[sis_term_id] string

The unique SIS identifier for the term.

enrollment_term[overrides][enrollment_type][start_at] DateTime

The day/time the term starts, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment

enrollment_term[overrides][enrollment_type][end_at] DateTime

The day/time the term ends, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment

override_sis_stickiness boolean

Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness

Returns an EnrollmentTerm object

Delete enrollment term TermsController#destroy

DELETE /api/v1/accounts/:account_id/terms/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/terms/:id

Delete the specified enrollment term.

Returns an EnrollmentTerm object

List enrollment terms TermsApiController#index

GET /api/v1/accounts/:account_id/terms

Scope: url:GET|/api/v1/accounts/:account_id/terms

An object with a paginated list of all of the terms in the account.

Request Parameters:

Parameter Type Description
workflow_state[] string

If set, only returns terms that are in the given state. Defaults to ‘active’.

Allowed values: active, deleted, all

include[] string

Array of additional information to include.

“overrides”

term start/end dates overridden for different enrollment types

“course_count”

the number of courses in each term

Allowed values: overrides

term_name string

If set, only returns terms that match the given search keyword. Search keyword is matched against term name.

Example Request:

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/1/terms?include[]=overrides

Example Response:

{
  "enrollment_terms": [
    {
      "id": 1,
      "name": "Fall 20X6"
      "start_at": "2026-08-31T20:00:00Z",
      "end_at": "2026-12-20T20:00:00Z",
      "created_at": "2025-01-02T03:43:11Z",
      "workflow_state": "active",
      "grading_period_group_id": 1,
      "sis_term_id": null,
      "overrides": {
        "StudentEnrollment": {
          "start_at": "2026-09-03T20:00:00Z",
          "end_at": "2026-12-19T20:00:00Z"
        },
        "TeacherEnrollment": {
          "start_at": null,
          "end_at": "2026-12-30T20:00:00Z"
        }
      }
    }
  ]
}
Returns an EnrollmentTermsList object

Retrieve enrollment term TermsApiController#show

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

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

Retrieves the details for an enrollment term in the account. Includes overrides by default.

Example Request:

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/1/terms/2
Returns an EnrollmentTerm object

List enrollments EnrollmentsApiController#index

GET /api/v1/courses/:course_id/enrollments

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

GET /api/v1/sections/:section_id/enrollments

Scope: url:GET|/api/v1/sections/:section_id/enrollments

GET /api/v1/users/:user_id/enrollments

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

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.

Request Parameters:

Parameter Type Description
type[] string

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.

role[] string

A list of enrollment roles to return. Accepted values include course-level roles created by the Add Role API as well as the base enrollment types accepted by the ‘type` argument above.

state[] string

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

Allowed values: active, invited, creation_pending, deleted, rejected, completed, inactive, current_and_invited, current_and_future, current_future_and_restricted, current_and_concluded

include[] string

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.

Allowed values: avatar_url, group_ids, locked, observed_users, can_be_removed, uuid, current_points

user_id string

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.

grading_period_id integer

Return grades for the given grading_period. If this parameter is not specified, the returned grades will be for the whole course.

enrollment_term_id integer

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:’.

sis_account_id[] string

Returns only enrollments for the specified SIS account ID(s). Does not look into sub_accounts. May pass in array or string.

sis_course_id[] string

Returns only enrollments matching the specified SIS course ID(s). May pass in array or string.

sis_section_id[] string

Returns only section enrollments matching the specified SIS section ID(s). May pass in array or string.

sis_user_id[] string

Returns only enrollments for the specified SIS user ID(s). May pass in array or string.

created_for_sis_id[] boolean

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

Returns a list of Enrollment objects

Enrollment by ID EnrollmentsApiController#show

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

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

Get an Enrollment object by Enrollment ID

Request Parameters:

Parameter Type Description
id Required integer

The ID of the enrollment object

Returns an Enrollment object

Enroll a user EnrollmentsApiController#create

POST /api/v1/courses/:course_id/enrollments

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

POST /api/v1/sections/:section_id/enrollments

Scope: url:POST|/api/v1/sections/:section_id/enrollments

Create a new user enrollment for a course or section.

Request Parameters:

Parameter Type Description
enrollment[start_at] DateTime

The start time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z

enrollment[end_at] DateTime

The end time of the enrollment, in ISO8601 format. e.g. 2012-04-18T23:08:51Z

enrollment[user_id] Required string

The ID of the user to be enrolled in the course.

enrollment[type] Required string

Enroll the user as a student, teacher, TA, observer, or designer. If no value is given, the type will be inferred by enrollment if supplied, otherwise ‘StudentEnrollment’ will be used.

Allowed values: StudentEnrollment, TeacherEnrollment, TaEnrollment, ObserverEnrollment, DesignerEnrollment

enrollment[role] Deprecated

Assigns a custom course-level role to the user.

enrollment[role_id] integer

Assigns a custom course-level role to the user.

enrollment[enrollment_state] string

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.

Allowed values: active, invited, inactive

enrollment[course_section_id] integer

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

If set, the enrollment will only allow the user to see and interact with users enrolled in the section given by course_section_id.

  • For teachers and TAs, this includes grading privileges.

  • Section-limited students will not see any users (including teachers and TAs) not enrolled in their sections.

  • Users may have other enrollments that grant privileges to multiple sections in the same course.

enrollment[notify] boolean

If true, a notification will be sent to the enrolled user. Notifications are not sent by default.

enrollment[self_enrollment_code] string

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

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

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 User Observees API.

enrollment[sis_user_id] string

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

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 string

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.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments \
  -X POST \
  -F 'enrollment[user_id]=1' \
  -F 'enrollment[type]=StudentEnrollment' \
  -F 'enrollment[enrollment_state]=active' \
  -F 'enrollment[course_section_id]=1' \
  -F 'enrollment[limit_privileges_to_course_section]=true' \
  -F 'enrollment[notify]=false'

curl https://<canvas>/api/v1/courses/:course_id/enrollments \
  -X POST \
  -F 'enrollment[user_id]=2' \
  -F 'enrollment[type]=StudentEnrollment'
Returns an Enrollment object

Conclude, deactivate, or delete an enrollment EnrollmentsApiController#destroy

DELETE /api/v1/courses/:course_id/enrollments/:id

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

Conclude, deactivate, or delete an enrollment. If the task argument isn’t given, the enrollment will be concluded.

Request Parameters:

Parameter Type Description
task string

The action to take on the enrollment. When inactive, a user will still appear in the course roster to admins, but be unable to participate. (“inactivate” and “deactivate” are equivalent tasks)

Allowed values: conclude, delete, inactivate, deactivate

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id \
  -X DELETE \
  -F 'task=conclude'
Returns an Enrollment object

Accept Course Invitation EnrollmentsApiController#accept

POST /api/v1/courses/:course_id/enrollments/:id/accept

Scope: url:POST|/api/v1/courses/:course_id/enrollments/:id/accept

accepts a pending course invitation for the current user

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/enrollments/:id/accept \
  -X POST \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "success": true
}

Reject Course Invitation EnrollmentsApiController#reject

POST /api/v1/courses/:course_id/enrollments/:id/reject

Scope: url:POST|/api/v1/courses/:course_id/enrollments/:id/reject

rejects a pending course invitation for the current user

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/enrollments/:id/reject \
  -X POST \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "success": true
}

Re-activate an enrollment EnrollmentsApiController#reactivate

PUT /api/v1/courses/:course_id/enrollments/:id/reactivate

Scope: url:PUT|/api/v1/courses/:course_id/enrollments/:id/reactivate

Activates an inactive enrollment

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id/reactivate \
  -X PUT
Returns an Enrollment object

Add last attended date EnrollmentsApiController#last_attended

PUT /api/v1/courses/:course_id/users/:user_id/last_attended

Scope: url:PUT|/api/v1/courses/:course_id/users/:user_id/last_attended

Add last attended date to student enrollment in course

Request Parameters:

Parameter Type Description
date Date

The last attended date of a student enrollment in a course.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/user/:user_id/last_attended"
  -X PUT => date="Thu%20Dec%2021%202017%2000:00:00%20GMT-0700%20(MST)
Returns an Enrollment object

Show Temporary Enrollment recipient and provider status EnrollmentsApiController#show_temporary_enrollment_status

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/users/:user_id/temporary_enrollment_status

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

Returns a JSON Object containing the temporary enrollment status for a user.

Request Parameters:

Parameter Type Description
account_id string

The ID of the account to check for temporary enrollment status. Defaults to the domain root account if not provided.

Example Response:

{
  "is_provider": false, "is_recipient": true, "can_provide": false
}

Get all ePortfolios for a User EportfoliosApiController#index

GET /api/v1/users/:user_id/eportfolios

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

Get a list of all ePortfolios for the specified user.

Request Parameters:

Parameter Type Description
include[] string
deleted

Include deleted ePortfolios. Only available to admins who can

moderate_user_content.

Allowed values: deleted

Returns a list of ePortfolio objects

Get an ePortfolio EportfoliosApiController#show

GET /api/v1/eportfolios/:id

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

Get details for a single ePortfolio.

Returns an ePortfolio object

Delete an ePortfolio EportfoliosApiController#delete

DELETE /api/v1/eportfolios/:id

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

Mark an ePortfolio as deleted.

Returns an ePortfolio object

Get ePortfolio Pages EportfoliosApiController#pages

GET /api/v1/eportfolios/:eportfolio_id/pages

Scope: url:GET|/api/v1/eportfolios/:eportfolio_id/pages

Get details for the pages of an ePortfolio

Returns a list of ePortfolioPage objects

Moderate an ePortfolio EportfoliosApiController#moderate

PUT /api/v1/eportfolios/:eportfolio_id/moderate

Scope: url:PUT|/api/v1/eportfolios/:eportfolio_id/moderate

Update the spam_status of an eportfolio. Only available to admins who can moderate_user_content.

Request Parameters:

Parameter Type Description
spam_status string

The spam status for the ePortfolio

Allowed values: marked_as_spam, marked_as_safe

Returns an ePortfolio object

Moderate all ePortfolios for a User EportfoliosApiController#moderate_all

PUT /api/v1/users/:user_id/eportfolios

Scope: url:PUT|/api/v1/users/:user_id/eportfolios

Update the spam_status for all active eportfolios of a user. Only available to admins who can moderate_user_content.

Request Parameters:

Parameter Type Description
spam_status string

The spam status for all the ePortfolios

Allowed values: marked_as_spam, marked_as_safe

Restore a deleted ePortfolio EportfoliosApiController#restore

PUT /api/v1/eportfolios/:eportfolio_id/restore

Scope: url:PUT|/api/v1/eportfolios/:eportfolio_id/restore

Restore an ePortfolio back to active that was previously deleted. Only available to admins who can moderate_user_content.

Returns an ePortfolio object

List courses with their latest ePub export EpubExportsController#index

GET /api/v1/epub_exports

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

A paginated list of all courses a user is actively participating in, and the latest ePub export associated with the user & course.

Returns a list of CourseEpubExport objects

Create ePub Export EpubExportsController#create

POST /api/v1/courses/:course_id/epub_exports

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

Begin an ePub export for a course.

You can use the Progress API to track the progress of the export. The export’s progress is linked to with the progress_url value.

When the export completes, use the Show content export endpoint to retrieve a download URL for the exported content.

Returns an EpubExport object

Show ePub export EpubExportsController#show

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

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

Get information about a single ePub export.

Returns an EpubExport object

Create Error Report ErrorsController#create

POST /api/v1/error_reports

Scope: url:POST|/api/v1/error_reports

Create a new error report documenting an experienced problem

Performs the same action as when a user uses the “help -> report a problem” dialog.

Request Parameters:

Parameter Type Description
error[subject] Required string

The summary of the problem

error[url] string

URL from which the report was issued

error[email] string

Email address for the reporting user

error[comments] string

The long version of the story from the user one what they experienced

error[http_env] SerializedHash

A collection of metadata about the users’ environment. If not provided, canvas will collect it based on information found in the request. (Doesn’t have to be HTTPENV info, could be anything JSON object that can be serialized as a hash, a mobile app might include relevant metadata for itself)

Example Request:

# Create error report
curl 'https://<canvas>/api/v1/error_reports' \
      -X POST \
      -F 'error[subject]="things are broken"' \
      -F 'error[url]=http://<canvas>/courses/1' \
      -F 'error[description]="All my thoughts on what I saw"' \
      -H 'Authorization: Bearer <token>'

List external tools ExternalToolsController#index

GET /api/v1/courses/:course_id/external_tools

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

GET /api/v1/accounts/:account_id/external_tools

Scope: url:GET|/api/v1/accounts/:account_id/external_tools

GET /api/v1/groups/:group_id/external_tools

Scope: url:GET|/api/v1/groups/:group_id/external_tools

Returns the paginated list of external tools for the current context. See the get request docs for a single tool for a list of properties on an external tool.

Request Parameters:

Parameter Type Description
search_term string

The partial name of the tools to match and return.

selectable boolean

If true, then only tools that are meant to be selectable are returned.

include_parents boolean

If true, then include tools installed in all accounts above the current context

placement string

The placement type to filter by.

Example Request:

Return all tools at the current context as well as all tools from the parent, and filter the tools list to only those with a placement of 'editor_button'
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools?include_parents=true&placement=editor_button' \
     -H "Authorization: Bearer <token>"

Example Response:

[
 {
   "id": 1,
   "domain": "domain.example.com",
   "url": "http://www.example.com/ims/lti",
   "consumer_key": "key",
   "name": "LTI Tool",
   "description": "This is for cool things",
   "created_at": "2037-07-21T13:29:31Z",
   "updated_at": "2037-07-28T19:38:31Z",
   "privacy_level": "anonymous",
   "custom_fields": {"key": "value"},
   "is_rce_favorite": false,
   "is_top_nav_favorite": false,
   "account_navigation": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "text": "...",
        "url": "...",
        "label": "...",
        "selection_width": 50,
        "selection_height":50
   },
   "assignment_selection": null,
   "course_home_sub_navigation": null,
   "course_navigation": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "text": "...",
        "url": "...",
        "default": "disabled",
        "enabled": "true",
        "visibility": "public",
        "windowTarget": "_blank"
   },
   "editor_button": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "message_type": "ContentItemSelectionRequest",
        "text": "...",
        "url": "...",
        "label": "...",
        "selection_width": 50,
        "selection_height": 50
   },
   "homework_submission": null,
   "link_selection": null,
   "migration_selection": null,
   "resource_selection": null,
   "tool_configuration": null,
   "user_navigation": null,
   "selection_width": 500,
   "selection_height": 500,
   "icon_url": "...",
   "not_selectable": false,
   "deployment_id": null,
   "unified_tool_id": null
 },
 { ...  }
]

Get a sessionless launch url for an external tool. ExternalToolsController#generate_sessionless_launch

GET /api/v1/courses/:course_id/external_tools/sessionless_launch

Scope: url:GET|/api/v1/courses/:course_id/external_tools/sessionless_launch

GET /api/v1/accounts/:account_id/external_tools/sessionless_launch

Scope: url:GET|/api/v1/accounts/:account_id/external_tools/sessionless_launch

Returns a sessionless launch url for an external tool. Prefers the resource_link_lookup_uuid, but defaults to the other passed

parameters id, url, and launch_type

NOTE: Either the resource_link_lookup_uuid, id, or url must be provided unless launch_type is assessment or module_item.

Request Parameters:

Parameter Type Description
id string

The external id of the tool to launch.

url string

The LTI launch url for the external tool.

assignment_id string

The assignment id for an assignment launch. Required if launch_type is set to “assessment”.

module_item_id string

The assignment id for a module item launch. Required if launch_type is set to “module_item”.

launch_type string

The type of launch to perform on the external tool. Placement names (eg. “course_navigation”) can also be specified to use the custom launch url for that placement; if done, the tool id must be provided.

Allowed values: assessment, module_item

resource_link_lookup_uuid string

The identifier to lookup a resource link.

API response field:

  • id

    The id for the external tool to be launched.

  • name

    The name of the external tool to be launched.

  • url

    The url to load to launch the external tool for the user.

Example Request:

Finds the tool by id and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'id=<external_tool_id>'

Finds the tool by launch url and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'url=<lti launch url>'

Finds the tool associated with a specific assignment and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'launch_type=assessment' \
     -F 'assignment_id=<assignment_id>'

Finds the tool associated with a specific module item and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'launch_type=module_item' \
     -F 'module_item_id=<module_item_id>'

Finds the tool by id and returns a sessionless launch url for a specific placement
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'id=<external_tool_id>' \
     -F 'launch_type=<placement_name>'

Get a single external tool ExternalToolsController#show

GET /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:GET|/api/v1/courses/:course_id/external_tools/:external_tool_id

GET /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:GET|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Returns the specified external tool.

API response field:

  • id

    The unique identifier for the tool

  • domain

    The domain to match links against

  • url

    The url to match links against

  • consumer_key

    The consumer key used by the tool (The associated shared secret is not returned)

  • name

    The name of the tool

  • description

    A description of the tool

  • created_at

    Timestamp of creation

  • updated_at

    Timestamp of last update

  • privacy_level

    How much user information to send to the external tool: “anonymous”, “name_only”, “email_only”, “public”

  • custom_fields

    Custom fields that will be sent to the tool consumer

  • is_rce_favorite

    Boolean determining whether this tool should be in a preferred location in the RCE.

  • is_top_nav_favorite

    Boolean determining whether this tool should have a dedicated button in Top Navigation.

  • account_navigation

    The configuration for account navigation links (see create API for values)

  • assignment_selection

    The configuration for assignment selection links (see create API for values)

  • course_home_sub_navigation

    The configuration for course home navigation links (see create API for values)

  • course_navigation

    The configuration for course navigation links (see create API for values)

  • editor_button

    The configuration for a WYSIWYG editor button (see create API for values)

  • homework_submission

    The configuration for homework submission selection (see create API for values)

  • link_selection

    The configuration for link selection (see create API for values)

  • migration_selection

    The configuration for migration selection (see create API for values)

  • resource_selection

    The configuration for a resource selector in modules (see create API for values)

  • tool_configuration

    The configuration for a tool configuration link (see create API for values)

  • user_navigation

    The configuration for user navigation links (see create API for values)

  • selection_width

    The pixel width of the iFrame that the tool will be rendered in

  • selection_height

    The pixel height of the iFrame that the tool will be rendered in

  • icon_url

    The url for the tool icon

  • not_selectable

    whether the tool is not selectable from assignment and modules

  • unified_tool_id

    The unique identifier for the tool in LearnPlatform

  • deployment_id

    The unique identifier for the deployment of the tool

Example Response:

{
  "id": 1,
  "domain": "domain.example.com",
  "url": "http://www.example.com/ims/lti",
  "consumer_key": "key",
  "name": "LTI Tool",
  "description": "This is for cool things",
  "created_at": "2037-07-21T13:29:31Z",
  "updated_at": "2037-07-28T19:38:31Z",
  "privacy_level": "anonymous",
  "custom_fields": {"key": "value"},
  "account_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "label": "...",
       "selection_width": 50,
       "selection_height":50
  },
  "assignment_selection": null,
  "course_home_sub_navigation": null,
  "course_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "default": "disabled",
       "enabled": "true",
       "visibility": "public",
       "windowTarget": "_blank"
  },
  "editor_button": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "message_type": "ContentItemSelectionRequest",
       "text": "...",
       "url": "...",
       "label": "...",
       "selection_width": 50,
       "selection_height": 50
  },
  "homework_submission": null,
  "link_selection": null,
  "migration_selection": null,
  "resource_selection": null,
  "tool_configuration": null,
  "user_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "default": "disabled",
       "enabled": "true",
       "visibility": "public",
       "windowTarget": "_blank"
  },
  "selection_width": 500,
  "selection_height": 500,
  "icon_url": "...",
  "not_selectable": false
}

Create an external tool ExternalToolsController#create

POST /api/v1/courses/:course_id/external_tools

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

POST /api/v1/accounts/:account_id/external_tools

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

Create an external tool in the specified course/account. The created tool will be returned, see the “show” endpoint for an example. If a client ID is supplied canvas will attempt to create a context external tool using the LTI 1.3 standard.

Request Parameters:

Parameter Type Description
client_id Required string

The client id is attached to the developer key. If supplied all other parameters are unnecessary and will be ignored

name Required string

The name of the tool

privacy_level Required string

How much user information to send to the external tool.

Allowed values: anonymous, name_only, email_only, public

consumer_key Required string

The consumer key for the external tool

shared_secret Required string

The shared secret with the external tool

description string

A description of the tool

url string

The url to match links against. Either “url” or “domain” should be set, not both.

domain string

The domain to match links against. Either “url” or “domain” should be set, not both.

icon_url string

The url of the icon to show for this tool

text string

The default text to show for this tool

custom_fields[field_name] string

Custom fields that will be sent to the tool consumer; can be used multiple times

is_rce_favorite boolean

(Deprecated in favor of Add tool to RCE Favorites and Remove tool from RCE Favorites) Whether this tool should appear in a preferred location in the RCE. This only applies to tools in root account contexts that have an editor button placement.

account_navigation[url] string

The url of the external tool for account navigation

account_navigation[enabled] boolean

Set this to enable this feature

account_navigation[text] string

The text that will show on the left-tab in the account navigation

account_navigation[selection_width] string

The width of the dialog the tool is launched in

account_navigation[selection_height] string

The height of the dialog the tool is launched in

account_navigation[display_type] string

The layout type to use when launching the tool. Must be “full_width”, “full_width_in_context”, “in_nav_context”, “borderless”, or “default”

user_navigation[url] string

The url of the external tool for user navigation

user_navigation[enabled] boolean

Set this to enable this feature

user_navigation[text] string

The text that will show on the left-tab in the user navigation

user_navigation[visibility] string

Who will see the navigation tab. “admins” for admins, “public” or “members” for everyone. Setting this to ‘null` will remove this configuration and use the default behavior, which is “public”.

Allowed values: admins, members, public

course_home_sub_navigation[url] string

The url of the external tool for right-side course home navigation menu

course_home_sub_navigation[enabled] boolean

Set this to enable this feature

course_home_sub_navigation[text] string

The text that will show on the right-side course home navigation menu

course_home_sub_navigation[icon_url] string

The url of the icon to show in the right-side course home navigation menu

course_navigation[enabled] boolean

Set this to enable this feature

course_navigation[text] string

The text that will show on the left-tab in the course navigation

course_navigation[visibility] string

Who will see the navigation tab. “admins” for course admins, “members” for students, “public” for everyone. Setting this to ‘null` will remove this configuration and use the default behavior, which is “public”.

Allowed values: admins, members, public

course_navigation[windowTarget] string

Determines how the navigation tab will be opened. “_blank” Launches the external tool in a new window or tab. “_self” (Default) Launches the external tool in an iframe inside of Canvas.

Allowed values: _blank, _self

course_navigation[default] string

If set to “disabled” the tool will not appear in the course navigation until a teacher explicitly enables it.

If set to “enabled” the tool will appear in the course navigation without requiring a teacher to explicitly enable it.

defaults to “enabled”

Allowed values: disabled, enabled

course_navigation[display_type] string

The layout type to use when launching the tool. Must be “full_width”, “full_width_in_context”, “in_nav_context”, “borderless”, or “default”

editor_button[url] string

The url of the external tool

editor_button[enabled] boolean

Set this to enable this feature

editor_button[icon_url] string

The url of the icon to show in the WYSIWYG editor

editor_button[selection_width] string

The width of the dialog the tool is launched in

editor_button[selection_height] string

The height of the dialog the tool is launched in

editor_button[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

homework_submission[url] string

The url of the external tool

homework_submission[enabled] boolean

Set this to enable this feature

homework_submission[text] string

The text that will show on the homework submission tab

homework_submission[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

link_selection[url] string

The url of the external tool

link_selection[enabled] boolean

Set this to enable this feature

link_selection[text] string

The text that will show for the link selection text

link_selection[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

migration_selection[url] string

The url of the external tool

migration_selection[enabled] boolean

Set this to enable this feature

migration_selection[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

tool_configuration[url] string

The url of the external tool

tool_configuration[enabled] boolean

Set this to enable this feature

tool_configuration[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit

tool_configuration[prefer_sis_email] boolean

Set this to default the lis_person_contact_email_primary to prefer provisioned sis_email; otherwise, omit

resource_selection[url] string

The url of the external tool

resource_selection[enabled] boolean

Set this to enable this feature. If set to false, not_selectable must also be set to true in order to hide this tool from the selection UI in modules and assignments.

resource_selection[icon_url] string

The url of the icon to show in the module external tool list

resource_selection[selection_width] string

The width of the dialog the tool is launched in

resource_selection[selection_height] string

The height of the dialog the tool is launched in

config_type string

Configuration can be passed in as CC xml instead of using query parameters. If this value is “by_url” or “by_xml” then an xml configuration will be expected in either the “config_xml” or “config_url” parameter. Note that the name parameter overrides the tool name provided in the xml

config_xml string

XML tool configuration, as specified in the CC xml specification. This is required if “config_type” is set to “by_xml”

config_url string

URL where the server can retrieve an XML tool configuration, as specified in the CC xml specification. This is required if “config_type” is set to “by_url”

not_selectable boolean

Default: false. If set to true, and if resource_selection is set to false, the tool won’t show up in the external tool selection UI in modules and assignments

oauth_compliant boolean

Default: false, if set to true LTI query params will not be copied to the post body.

unified_tool_id string

The unique identifier for the tool in LearnPlatform

Example Request:

This would create a tool on this course with two custom fields and a course navigation tab
curl -X POST 'https://<canvas>/api/v1/courses/<course_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \
     -F 'custom_fields[key1]=value1' \
     -F 'custom_fields[key2]=value2' \
     -F 'course_navigation[text]=Course Materials' \
     -F 'course_navigation[enabled]=true'

This would create a tool on the account with navigation for the user profile page
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \
     -F 'user_navigation[url]=https://example.com/ims/lti/user_endpoint' \
     -F 'user_navigation[text]=Something Cool'
     -F 'user_navigation[enabled]=true'

This would create a tool on the account with configuration pulled from an external URL
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'config_type=by_url' \
     -F 'config_url=https://example.com/ims/lti/tool_config.xml'

Edit an external tool ExternalToolsController#update

PUT /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:PUT|/api/v1/courses/:course_id/external_tools/:external_tool_id

PUT /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:PUT|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Update the specified external tool. Uses same parameters as create

Example Request:

This would update the specified keys on this external tool
curl -X PUT 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>" \
     -F 'name=Public Example' \
     -F 'privacy_level=public'

Delete an external tool ExternalToolsController#destroy

DELETE /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:DELETE|/api/v1/courses/:course_id/external_tools/:external_tool_id

DELETE /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Remove the specified external tool

Example Request:

This would delete the specified external tool
curl -X DELETE 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>"

Add tool to RCE Favorites ExternalToolsController#add_rce_favorite

POST /api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Scope: url:POST|/api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Add the specified editor_button external tool to a preferred location in the RCE for courses in the given account and its subaccounts (if the subaccounts haven’t set their own RCE Favorites). Cannot set more than 2 RCE Favorites.

Example Request:

curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/rce_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Remove tool from RCE Favorites ExternalToolsController#remove_rce_favorite

DELETE /api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/rce_favorites/:id

Remove the specified external tool from a preferred location in the RCE for the given account

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/rce_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Add tool to Top Navigation Favorites ExternalToolsController#add_top_nav_favorite

POST /api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Scope: url:POST|/api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Adds a dedicated button in Top Navigation for the specified tool for the given account. Cannot set more than 2 top_navigation Favorites.

Example Request:

curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/top_nav_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Remove tool from Top Navigation Favorites ExternalToolsController#remove_top_nav_favorite

DELETE /api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/top_nav_favorites/:id

Removes the dedicated button in Top Navigation for the specified tool for the given account.

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/accounts/<account_id>/external_tools/top_nav_favorites/<id>' \
     -H "Authorization: Bearer <token>"

Get visible course navigation tools ExternalToolsController#all_visible_nav_tools

GET /api/v1/external_tools/visible_course_nav_tools

Scope: url:GET|/api/v1/external_tools/visible_course_nav_tools

Get a list of external tools with the course_navigation placement that have not been hidden in course settings and whose visibility settings apply to the requesting user. These tools are the same that appear in the course navigation.

The response format is the same as for List external tools, but with additional context_id and context_name fields on each element in the array.

Request Parameters:

Parameter Type Description
context_codes[] Required string

List of context_codes to retrieve visible course nav tools for (for example, course_123). Only courses are presently supported.

API response field:

  • context_id

    The unique identifier of the associated context

  • context_name

    The name of the associated context

Example Request:

curl 'https://<canvas>/api/v1/external_tools/visible_course_nav_tools?context_codes[]=course_5' \
     -H "Authorization: Bearer <token>"

Example Response:

[{
  "id": 1,
  "domain": "domain.example.com",
  "url": "http://www.example.com/ims/lti",
  "context_id": 5,
  "context_name": "Example Course",
  ...
},
{ ...  }]

Get visible course navigation tools for a single course ExternalToolsController#visible_course_nav_tools

GET /api/v1/courses/:course_id/external_tools/visible_course_nav_tools

Scope: url:GET|/api/v1/courses/:course_id/external_tools/visible_course_nav_tools

Get a list of external tools with the course_navigation placement that have not been hidden in course settings and whose visibility settings apply to the requesting user. These tools are the same that appear in the course navigation.

The response format is the same as Get visible course navigation tools.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/visible_course_nav_tools' \
     -H "Authorization: Bearer <token>"

List favorite courses FavoritesController#list_favorite_courses

GET /api/v1/users/self/favorites/courses

Scope: url:GET|/api/v1/users/self/favorites/courses

Retrieve the paginated list of favorite courses for the current user. If the user has not chosen any favorites, then a selection of currently enrolled courses will be returned.

See the List courses API for details on accepted include[] parameters.

Request Parameters:

Parameter Type Description
exclude_blueprint_courses boolean

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

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a list of Course objects

List favorite groups FavoritesController#list_favorite_groups

GET /api/v1/users/self/favorites/groups

Scope: url:GET|/api/v1/users/self/favorites/groups

Retrieve the paginated list of favorite groups for the current user. If the user has not chosen any favorites, then a selection of groups that the user is a member of will be returned.

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/groups \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a list of Group objects

Add course to favorites FavoritesController#add_favorite_course

POST /api/v1/users/self/favorites/courses/:id

Scope: url:POST|/api/v1/users/self/favorites/courses/:id

Add a course to the current user’s favorites. If the course is already in the user’s favorites, nothing happens. Canvas for Elementary subject and homeroom courses can be added to favorites, but this has no effect in the UI.

Request Parameters:

Parameter Type Description
id Required string

The ID or SIS ID of the course to add. The current user must be registered in the course.

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses/1170 \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Length: 0'
Returns a Favorite object

Add group to favorites FavoritesController#add_favorite_groups

POST /api/v1/users/self/favorites/groups/:id

Scope: url:POST|/api/v1/users/self/favorites/groups/:id

Add a group to the current user’s favorites. If the group is already in the user’s favorites, nothing happens.

Request Parameters:

Parameter Type Description
id Required string

The ID or SIS ID of the group to add. The current user must be a member of the group.

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/group/1170 \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Length: 0'
Returns a Favorite object

Remove course from favorites FavoritesController#remove_favorite_course

DELETE /api/v1/users/self/favorites/courses/:id

Scope: url:DELETE|/api/v1/users/self/favorites/courses/:id

Remove a course from the current user’s favorites.

Request Parameters:

Parameter Type Description
id Required string

the ID or SIS ID of the course to remove

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses/1170 \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a Favorite object

Remove group from favorites FavoritesController#remove_favorite_groups

DELETE /api/v1/users/self/favorites/groups/:id

Scope: url:DELETE|/api/v1/users/self/favorites/groups/:id

Remove a group from the current user’s favorites.

Request Parameters:

Parameter Type Description
id Required string

the ID or SIS ID of the group to remove

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/groups/1170 \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a Favorite object

Reset course favorites FavoritesController#reset_course_favorites

DELETE /api/v1/users/self/favorites/courses

Scope: url:DELETE|/api/v1/users/self/favorites/courses

Reset the current user’s course favorites to the default automatically generated list of enrolled courses

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Reset group favorites FavoritesController#reset_groups_favorites

DELETE /api/v1/users/self/favorites/groups

Scope: url:DELETE|/api/v1/users/self/favorites/groups

Reset the current user’s group favorites to the default automatically generated list of enrolled group

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/group \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

List features FeatureFlagsController#index

GET /api/v1/courses/:course_id/features

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

GET /api/v1/accounts/:account_id/features

Scope: url:GET|/api/v1/accounts/:account_id/features

GET /api/v1/users/:user_id/features

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

A paginated list of all features that apply to a given Account, Course, or User.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features' \
  -H "Authorization: Bearer <token>"
Returns a list of Feature objects

List enabled features FeatureFlagsController#enabled_features

GET /api/v1/courses/:course_id/features/enabled

Scope: url:GET|/api/v1/courses/:course_id/features/enabled

GET /api/v1/accounts/:account_id/features/enabled

Scope: url:GET|/api/v1/accounts/:account_id/features/enabled

GET /api/v1/users/:user_id/features/enabled

Scope: url:GET|/api/v1/users/:user_id/features/enabled

A paginated list of all features that are enabled on a given Account, Course, or User. Only the feature names are returned.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features/enabled' \
  -H "Authorization: Bearer <token>"

Example Response:

["fancy_wickets", "automatic_essay_grading", "telepathic_navigation"]

List environment features FeatureFlagsController#environment

GET /api/v1/features/environment

Scope: url:GET|/api/v1/features/environment

Return a hash of global feature options that pertain to the Canvas user interface. This is the same information supplied to the web interface as ENV.FEATURES.

Example Request:

curl 'http://<canvas>/api/v1/features/environment' \
  -H "Authorization: Bearer <token>"

Example Response:

{ "telepathic_navigation": true, "fancy_wickets": true, "automatic_essay_grading": false }

Get feature flag FeatureFlagsController#show

GET /api/v1/courses/:course_id/features/flags/:feature

Scope: url:GET|/api/v1/courses/:course_id/features/flags/:feature

GET /api/v1/accounts/:account_id/features/flags/:feature

Scope: url:GET|/api/v1/accounts/:account_id/features/flags/:feature

GET /api/v1/users/:user_id/features/flags/:feature

Scope: url:GET|/api/v1/users/:user_id/features/flags/:feature

Get the feature flag that applies to a given Account, Course, or User. The flag may be defined on the object, or it may be inherited from a parent account. You can look at the context_id and context_type of the returned object to determine which is the case. If these fields are missing, then the object is the global Canvas default.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer <token>"
Returns a FeatureFlag object

Set feature flag FeatureFlagsController#update

PUT /api/v1/courses/:course_id/features/flags/:feature

Scope: url:PUT|/api/v1/courses/:course_id/features/flags/:feature

PUT /api/v1/accounts/:account_id/features/flags/:feature

Scope: url:PUT|/api/v1/accounts/:account_id/features/flags/:feature

PUT /api/v1/users/:user_id/features/flags/:feature

Scope: url:PUT|/api/v1/users/:user_id/features/flags/:feature

Set a feature flag for a given Account, Course, or User. This call will fail if a parent account sets a feature flag for the same feature in any state other than “allowed”.

Request Parameters:

Parameter Type Description
state string
“off”

The feature is not available for the course, user, or account and sub-accounts.

“allowed”

(valid only on accounts) The feature is off in the account, but may be enabled in sub-accounts and courses by setting a feature flag on the sub-account or course.

“on”

The feature is turned on unconditionally for the user, course, or account and sub-accounts.

Allowed values: off, allowed, on

Example Request:

curl -X PUT 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer " \
  -F "state=on"
Returns a FeatureFlag object

Remove feature flag FeatureFlagsController#delete

DELETE /api/v1/courses/:course_id/features/flags/:feature

Scope: url:DELETE|/api/v1/courses/:course_id/features/flags/:feature

DELETE /api/v1/accounts/:account_id/features/flags/:feature

Scope: url:DELETE|/api/v1/accounts/:account_id/features/flags/:feature

DELETE /api/v1/users/:user_id/features/flags/:feature

Scope: url:DELETE|/api/v1/users/:user_id/features/flags/:feature

Remove feature flag for a given Account, Course, or User. (Note that the flag must be defined on the Account, Course, or User directly.) The object will then inherit the feature flags from a higher account, if any exist. If this flag was ‘on’ or ‘off’, then lower-level account flags that were masked by this one will apply again.

Example Request:

curl -X DELETE 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer <token>"
Returns a FeatureFlag object

Get quota information FilesController#api_quota

GET /api/v1/courses/:course_id/files/quota

Scope: url:GET|/api/v1/courses/:course_id/files/quota

GET /api/v1/groups/:group_id/files/quota

Scope: url:GET|/api/v1/groups/:group_id/files/quota

GET /api/v1/users/:user_id/files/quota

Scope: url:GET|/api/v1/users/:user_id/files/quota

Returns the total and used storage quota for the course, group, or user.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/files/quota' \
      -H 'Authorization: Bearer <token>'

Example Response:

{ "quota": 524288000, "quota_used": 402653184 }

List files FilesController#api_index

GET /api/v1/courses/:course_id/files

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

GET /api/v1/users/:user_id/files

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

GET /api/v1/groups/:group_id/files

Scope: url:GET|/api/v1/groups/:group_id/files

GET /api/v1/folders/:id/files

Scope: url:GET|/api/v1/folders/:id/files

Returns the paginated list of files for the folder or course.

Request Parameters:

Parameter Type Description
content_types[] string

Filter results by content-type. You can specify type/subtype pairs (e.g., ‘image/jpeg’), or simply types (e.g., ‘image’, which will match ‘image/gif’, ‘image/jpeg’, etc.).

exclude_content_types[] string

Exclude given content-types from your results. You can specify type/subtype pairs (e.g., ‘image/jpeg’), or simply types (e.g., ‘image’, which will match ‘image/gif’, ‘image/jpeg’, etc.).

search_term string

The partial name of the files to match and return.

include[] string

Array of additional information to include.

“user”

the user who uploaded the file or last edited its content

“usage_rights”

copyright and license information for the file (see UsageRights)

Allowed values: user

only[] Array

Array of information to restrict to. Overrides include[]

“names”

only returns file name information

sort string

Sort results by this field. Defaults to ‘name’. Note that ‘sort=user` implies `include[]=user`.

Allowed values: name, size, created_at, updated_at, content_type, user

order string

The sorting order. Defaults to ‘asc’.

Allowed values: asc, desc

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/files?content_types[]=image&content_types[]=text/plain \
      -H 'Authorization: Bearer <token>'
Returns a list of File objects

Get public inline preview url FilesController#public_url

GET /api/v1/files/:id/public_url

Scope: url:GET|/api/v1/files/:id/public_url

Determine the URL that should be used for inline preview of the file.

Request Parameters:

Parameter Type Description
submission_id integer

The id of the submission the file is associated with. Provide this argument to gain access to a file that has been submitted to an assignment (Canvas will verify that the file belongs to the submission and the calling user has rights to view the submission).

Example Request:

curl 'https://<canvas>/api/v1/files/1/public_url' \
      -H 'Authorization: Bearer <token>'

Example Response:

{ "public_url": "https://example-bucket.s3.amazonaws.com/example-namespace/attachments/1/example-filename?AWSAccessKeyId=example-key&Expires=1400000000&Signature=example-signature" }

Get file FilesController#api_show

GET /api/v1/files/:id

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

POST /api/v1/files/:id

Scope: url:POST|/api/v1/files/:id

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

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

GET /api/v1/groups/:group_id/files/:id

Scope: url:GET|/api/v1/groups/:group_id/files/:id

GET /api/v1/users/:user_id/files/:id

Scope: url:GET|/api/v1/users/:user_id/files/:id

Returns the standard attachment json object

Request Parameters:

Parameter Type Description
include[] string

Array of additional information to include.

“user”

the user who uploaded the file or last edited its content

“usage_rights”

copyright and license information for the file (see UsageRights)

Allowed values: user

replacement_chain_context_type string

When a user replaces a file during upload, Canvas keeps track of the “replacement chain.”

Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another.

Must be set to ‘course’ or ‘account’. The “replacement_chain_context_id” parameter must also be included.

replacement_chain_context_id integer

When a user replaces a file during upload, Canvas keeps track of the “replacement chain.”

Include this parameter if you wish Canvas to follow the replacement chain if the requested file was deleted and replaced by another.

Indicates the context ID Canvas should use when following the “replacement chain.” The “replacement_chain_context_type” parameter must also be included.

Example Request:

curl 'https://<canvas>/api/v1/files/<file_id>' \
      -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/courses/<course_id>/files/<file_id>' \
      -H 'Authorization: Bearer <token>'
Returns a File object

Translate file reference FilesController#file_ref

GET /api/v1/courses/:course_id/files/file_ref/:migration_id

Scope: url:GET|/api/v1/courses/:course_id/files/file_ref/:migration_id

Get information about a file from a course copy file reference

Example Request:

curl https://<canvas>/api/v1/courses/1/files/file_ref/i567b573b77fab13a1a39937c24ae88f2 \
     -H 'Authorization: Bearer <token>'
Returns a File object

Update file FilesController#api_update

PUT /api/v1/files/:id

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

Update some settings on the specified file

Request Parameters:

Parameter Type Description
name string

The new display name of the file, with a limit of 255 characters.

parent_folder_id string

The id of the folder to move this file into. The new folder must be in the same context as the original parent folder. If the file is in a context without folders this does not apply.

on_duplicate string

If the file is moved to a folder containing a file with the same name, or renamed to a name matching an existing file, the API call will fail unless this parameter is supplied.

“overwrite”

Replace the existing file with the same name

“rename”

Add a qualifier to make the new filename unique

Allowed values: overwrite, rename

lock_at DateTime

The datetime to lock the file at

unlock_at DateTime

The datetime to unlock the file at

locked boolean

Flag the file as locked

hidden boolean

Flag the file as hidden

visibility_level string

Configure which roles can access this file

Example Request:

curl -X PUT 'https://<canvas>/api/v1/files/<file_id>' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a File object

Delete file FilesController#destroy

DELETE /api/v1/files/:id

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

Remove the specified file. Unlike most other DELETE endpoints, using this endpoint will result in comprehensive, irretrievable destruction of the file. It should be used with the ‘replace` parameter set to true in cases where the file preview also needs to be destroyed (such as to remove files that violate privacy laws).

Request Parameters:

Parameter Type Description
replace boolean

This action is irreversible. If replace is set to true the file contents will be replaced with a generic “file has been removed” file. This also destroys any previews that have been generated for the file. Must have manage files and become other users permissions

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/files/<file_id>' \
     -H 'Authorization: Bearer <token>'
Returns a File object

Get icon metadata FilesController#icon_metadata

GET /api/v1/files/:id/icon_metadata

Scope: url:GET|/api/v1/files/:id/icon_metadata

Returns the icon maker file attachment metadata

Example Request:

curl 'https://<canvas>/api/v1/courses/1/files/1/metadata' \
      -H 'Authorization: Bearer <token>'

Example Response:

{
  "type":"image/svg+xml-icon-maker-icons",
  "alt":"",
  "shape":"square",
  "size":"small",
  "color":"#FFFFFF",
  "outlineColor":"#65499D",
  "outlineSize":"large",
  "text":"Hello",
  "textSize":"x-large",
  "textColor":"#65499D",
  "textBackgroundColor":"#FFFFFF",
  "textPosition":"bottom-third",
  "encodedImage":"data:image/svg+xml;base64,PH==",
  "encodedImageType":"SingleColor",
  "encodedImageName":"Health Icon",
  "x":"50%",
  "y":"50%",
  "translateX":-54,
  "translateY":-54,
  "width":108,
  "height":108,
  "transform":"translate(-54,-54)"
}

Reset link verifier FilesController#reset_verifier

POST /api/v1/files/:id/reset_verifier

Scope: url:POST|/api/v1/files/:id/reset_verifier

Resets the link verifier. Any existing links to the file using the previous hard-coded “verifier” parameter will no longer automatically grant access.

Must have manage files and become other users permissions

Example Request:

curl -X POST 'https://<canvas>/api/v1/files/<file_id>/reset_verifier' \
     -H 'Authorization: Bearer <token>'
Returns a File object

List folders FoldersController#api_index

GET /api/v1/folders/:id/folders

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

Returns the paginated list of folders in the folder.

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/folders' \
     -H 'Authorization: Bearer <token>'
Returns a list of Folder objects

List folders and files FoldersController#list_folders_and_files

GET /api/v1/folders/:id/all

Scope: url:GET|/api/v1/folders/:id/all

Returns the paginated list of folders in the folder and files.

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/all' \
     -H 'Authorization: Bearer <token>'
Returns a list of Folder objects

List all folders FoldersController#list_all_folders

GET /api/v1/courses/:course_id/folders

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

GET /api/v1/users/:user_id/folders

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

GET /api/v1/groups/:group_id/folders

Scope: url:GET|/api/v1/groups/:group_id/folders

Returns the paginated list of all folders for the given context. This will be returned as a flat list containing all subfolders as well.

Example Request:

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

Resolve path FoldersController#resolve_path

GET /api/v1/courses/:course_id/folders/by_path/*full_path

Scope: url:GET|/api/v1/courses/:course_id/folders/by_path/*full_path

GET /api/v1/courses/:course_id/folders/by_path

Scope: url:GET|/api/v1/courses/:course_id/folders/by_path

GET /api/v1/users/:user_id/folders/by_path/*full_path

Scope: url:GET|/api/v1/users/:user_id/folders/by_path/*full_path

GET /api/v1/users/:user_id/folders/by_path

Scope: url:GET|/api/v1/users/:user_id/folders/by_path

GET /api/v1/groups/:group_id/folders/by_path/*full_path

Scope: url:GET|/api/v1/groups/:group_id/folders/by_path/*full_path

GET /api/v1/groups/:group_id/folders/by_path

Scope: url:GET|/api/v1/groups/:group_id/folders/by_path

Given the full path to a folder, returns a list of all Folders in the path hierarchy, starting at the root folder, and ending at the requested folder. The given path is relative to the context’s root folder and does not include the root folder’s name (e.g., “course files”). If an empty path is given, the context’s root folder alone is returned. Otherwise, if no folder exists with the given full path, a Not Found error is returned.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/folders/by_path/foo/bar/baz' \
     -H 'Authorization: Bearer <token>'
Returns a list of Folder objects

Get folder FoldersController#show

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

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

GET /api/v1/users/:user_id/folders/:id

Scope: url:GET|/api/v1/users/:user_id/folders/:id

GET /api/v1/groups/:group_id/folders/:id

Scope: url:GET|/api/v1/groups/:group_id/folders/:id

GET /api/v1/folders/:id

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

Returns the details for a folder

You can get the root folder from a context by using ‘root’ as the :id. For example, you could get the root folder for a course like:

Example Request:

curl 'https://<canvas>/api/v1/courses/1337/folders/root' \
     -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/folders/<folder_id>' \
     -H 'Authorization: Bearer <token>'
Returns a Folder object

Update folder FoldersController#update

PUT /api/v1/folders/:id

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

Updates a folder

Request Parameters:

Parameter Type Description
name string

The new name of the folder

parent_folder_id string

The id of the folder to move this folder into. The new folder must be in the same context as the original parent folder.

lock_at DateTime

The datetime to lock the folder at

unlock_at DateTime

The datetime to unlock the folder at

locked boolean

Flag the folder as locked

hidden boolean

Flag the folder as hidden

position integer

Set an explicit sort position for the folder

Example Request:

curl -XPUT 'https://<canvas>/api/v1/folders/<folder_id>' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a Folder object

Create folder FoldersController#create

POST /api/v1/courses/:course_id/folders

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

POST /api/v1/users/:user_id/folders

Scope: url:POST|/api/v1/users/:user_id/folders

POST /api/v1/groups/:group_id/folders

Scope: url:POST|/api/v1/groups/:group_id/folders

POST /api/v1/folders/:folder_id/folders

Scope: url:POST|/api/v1/folders/:folder_id/folders

POST /api/v1/accounts/:account_id/folders

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

Creates a folder in the specified context

Request Parameters:

Parameter Type Description
name Required string

The name of the folder

parent_folder_id string

The id of the folder to store the new folder in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used.

parent_folder_path string

The path of the folder to store the new folder in. The path separator is the forward slash ‘/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used.

lock_at DateTime

The datetime to lock the folder at

unlock_at DateTime

The datetime to unlock the folder at

locked boolean

Flag the folder as locked

hidden boolean

Flag the folder as hidden

position integer

Set an explicit sort position for the folder

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/folders' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/courses/<course_id>/folders' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a Folder object

Delete folder FoldersController#api_destroy

DELETE /api/v1/folders/:id

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

Remove the specified folder. You can only delete empty folders unless you set the ‘force’ flag

Request Parameters:

Parameter Type Description
force boolean

Set to ‘true’ to allow deleting a non-empty folder

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/folders/<folder_id>' \
     -H 'Authorization: Bearer <token>'

Upload a file FoldersController#create_file

POST /api/v1/folders/:folder_id/files

Scope: url:POST|/api/v1/folders/:folder_id/files

Upload a file to a folder.

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

Only those with the “Manage Files” permission on a course or group can upload files to a folder in that course or group.

Copy a file FoldersController#copy_file

POST /api/v1/folders/:dest_folder_id/copy_file

Scope: url:POST|/api/v1/folders/:dest_folder_id/copy_file

Copy a file from elsewhere in Canvas into a folder.

Copying a file across contexts (between courses and users) is permitted, but the source and destination must belong to the same institution.

Request Parameters:

Parameter Type Description
source_file_id Required string

The id of the source file

on_duplicate string

What to do if a file with the same name already exists at the destination. If such a file exists and this parameter is not given, the call will fail.

“overwrite”

Replace an existing file with the same name

“rename”

Add a qualifier to make the new filename unique

Allowed values: overwrite, rename

Example Request:

curl 'https://<canvas>/api/v1/folders/123/copy_file' \
     -H 'Authorization: Bearer <token>'
     -F 'source_file_id=456'
Returns a File object

Copy a folder FoldersController#copy_folder

POST /api/v1/folders/:dest_folder_id/copy_folder

Scope: url:POST|/api/v1/folders/:dest_folder_id/copy_folder

Copy a folder (and its contents) from elsewhere in Canvas into a folder.

Copying a folder across contexts (between courses and users) is permitted, but the source and destination must belong to the same institution. If the source and destination folders are in the same context, the source folder may not contain the destination folder. A folder will be renamed at its destination if another folder with the same name already exists.

Request Parameters:

Parameter Type Description
source_folder_id Required string

The id of the source folder

Example Request:

curl 'https://<canvas>/api/v1/folders/123/copy_folder' \
     -H 'Authorization: Bearer <token>'
     -F 'source_file_id=789'
Returns a Folder object

Get uploaded media folder for user FoldersController#media_folder

GET /api/v1/courses/:course_id/folders/media

Scope: url:GET|/api/v1/courses/:course_id/folders/media

GET /api/v1/groups/:group_id/folders/media

Scope: url:GET|/api/v1/groups/:group_id/folders/media

Returns the details for a designated upload folder that the user has rights to upload to, and creates it if it doesn’t exist.

If the current user does not have the permissions to manage files in the course or group, the folder will belong to the current user directly.

Example Request:

curl 'https://<canvas>/api/v1/courses/1337/folders/media' \
     -H 'Authorization: Bearer <token>'
Returns a Folder object

Set usage rights UsageRightsController#set_usage_rights

PUT /api/v1/courses/:course_id/usage_rights

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

PUT /api/v1/groups/:group_id/usage_rights

Scope: url:PUT|/api/v1/groups/:group_id/usage_rights

PUT /api/v1/users/:user_id/usage_rights

Scope: url:PUT|/api/v1/users/:user_id/usage_rights

Sets copyright and license information for one or more files

Request Parameters:

Parameter Type Description
file_ids[] Required string

List of ids of files to set usage rights for.

folder_ids[] string

List of ids of folders to search for files to set usage rights for. Note that new files uploaded to these folders do not automatically inherit these rights.

publish boolean

Whether the file(s) or folder(s) should be published on save, provided that usage rights have been specified (set to ‘true` to publish on save).

usage_rights[use_justification] Required string

The intellectual property justification for using the files in Canvas

Allowed values: own_copyright, used_by_permission, fair_use, public_domain, creative_commons

usage_rights[legal_copyright] string

The legal copyright line for the files

usage_rights[license] string

The license that applies to the files. See the List licenses endpoint for the supported license types.

Returns an UsageRights object

Remove usage rights UsageRightsController#remove_usage_rights

DELETE /api/v1/courses/:course_id/usage_rights

Scope: url:DELETE|/api/v1/courses/:course_id/usage_rights

DELETE /api/v1/groups/:group_id/usage_rights

Scope: url:DELETE|/api/v1/groups/:group_id/usage_rights

DELETE /api/v1/users/:user_id/usage_rights

Scope: url:DELETE|/api/v1/users/:user_id/usage_rights

Removes copyright and license information associated with one or more files

Request Parameters:

Parameter Type Description
file_ids[] Required string

List of ids of files to remove associated usage rights from.

folder_ids[] string

List of ids of folders. Usage rights will be removed from all files in these folders.

List licenses UsageRightsController#licenses

GET /api/v1/courses/:course_id/content_licenses

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

GET /api/v1/groups/:group_id/content_licenses

Scope: url:GET|/api/v1/groups/:group_id/content_licenses

GET /api/v1/users/:user_id/content_licenses

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

A paginated list of licenses that can be applied

Returns a list of License objects

Query by assignment GradeChangeAuditApiController#for_assignment

GET /api/v1/audit/grade_change/assignments/:assignment_id

Scope: url:GET|/api/v1/audit/grade_change/assignments/:assignment_id

List grade change events for a given assignment.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of GradeChangeEvent objects

Query by course GradeChangeAuditApiController#for_course

GET /api/v1/audit/grade_change/courses/:course_id

Scope: url:GET|/api/v1/audit/grade_change/courses/:course_id

List grade change events for a given course.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of GradeChangeEvent objects

Query by student GradeChangeAuditApiController#for_student

GET /api/v1/audit/grade_change/students/:student_id

Scope: url:GET|/api/v1/audit/grade_change/students/:student_id

List grade change events for a given student.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of GradeChangeEvent objects

Query by grader GradeChangeAuditApiController#for_grader

GET /api/v1/audit/grade_change/graders/:grader_id

Scope: url:GET|/api/v1/audit/grade_change/graders/:grader_id

List grade change events for a given grader.

Request Parameters:

Parameter Type Description
start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of GradeChangeEvent objects

Advanced query GradeChangeAuditApiController#query

GET /api/v1/audit/grade_change

Scope: url:GET|/api/v1/audit/grade_change

List grade change events satisfying all given parameters. Teachers may query for events in courses they teach. Queries without course_id require account administrator rights.

At least one of course_id, assignment_id, student_id, or grader_id must be specified.

Request Parameters:

Parameter Type Description
course_id integer

Restrict query to events in the specified course.

assignment_id integer

Restrict query to the given assignment. If “override” is given, query the course final grade override instead.

student_id integer

User id of a student to search grading events for.

grader_id integer

User id of a grader to search grading events for.

start_time DateTime

The beginning of the time range from which you want events.

end_time DateTime

The end of the time range from which you want events.

Returns a list of GradeChangeEvent objects

Days in gradebook history for this course GradebookHistoryApiController#days

GET /api/v1/courses/:course_id/gradebook_history/days

Scope: url:GET|/api/v1/courses/:course_id/gradebook_history/days

Returns a map of dates to grader/assignment groups

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the contextual course for this API call

Returns a list of Day objects

Details for a given date in gradebook history for this course GradebookHistoryApiController#day_details

GET /api/v1/courses/:course_id/gradebook_history/:date

Scope: url:GET|/api/v1/courses/:course_id/gradebook_history/:date

Returns the graders who worked on this day, along with the assignments they worked on. More details can be obtained by selecting a grader and assignment and calling the ‘submissions’ api endpoint for a given date.

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the contextual course for this API call

date Required string

The date for which you would like to see detailed information

Returns a list of Grader objects

Lists submissions GradebookHistoryApiController#submissions

GET /api/v1/courses/:course_id/gradebook_history/:date/graders/:grader_id/assignments/:assignment_id/submissions

Scope: url:GET|/api/v1/courses/:course_id/gradebook_history/:date/graders/:grader_id/assignments/:assignment_id/submissions

Gives a nested list of submission versions

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the contextual course for this API call

date Required string

The date for which you would like to see submissions

grader_id Required integer

The ID of the grader for which you want to see submissions

assignment_id Required integer

The ID of the assignment for which you want to see submissions

Returns a list of SubmissionHistory objects

List uncollated submission versions GradebookHistoryApiController#feed

GET /api/v1/courses/:course_id/gradebook_history/feed

Scope: url:GET|/api/v1/courses/:course_id/gradebook_history/feed

Gives a paginated, uncollated list of submission versions for all matching submissions in the context. This SubmissionVersion objects will not include the new_grade or previous_grade keys, only the grade; same for graded_at and grader.

Request Parameters:

Parameter Type Description
course_id Required integer

The id of the contextual course for this API call

assignment_id integer

The ID of the assignment for which you want to see submissions. If absent, versions of submissions from any assignment in the course are included.

user_id integer

The ID of the user for which you want to see submissions. If absent, versions of submissions from any user in the course are included.

ascending boolean

Returns submission versions in ascending date order (oldest first). If absent, returns submission versions in descending date order (newest first).

Returns a list of SubmissionVersion objects

List grading period sets GradingPeriodSetsController#index

GET /api/v1/accounts/:account_id/grading_period_sets

Scope: url:GET|/api/v1/accounts/:account_id/grading_period_sets

Returns the paginated list of grading period sets

Example Response:

{
  "grading_period_set": [GradingPeriodGroup]
}

Create a grading period set GradingPeriodSetsController#create

POST /api/v1/accounts/:account_id/grading_period_sets

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

Create and return a new grading period set

Request Parameters:

Parameter Type Description
enrollment_term_ids[] Array

A list of associated term ids for the grading period set

grading_period_set[title] Required string

The title of the grading period set

grading_period_set[weighted] boolean

A boolean to determine whether the grading periods in the set are weighted

grading_period_set[display_totals_for_all_grading_periods] boolean

A boolean to determine whether the totals for all grading periods in the set are displayed

Example Response:

{
  "grading_period_set": [GradingPeriodGroup]
}

Update a grading period set GradingPeriodSetsController#update

PATCH /api/v1/accounts/:account_id/grading_period_sets/:id

Scope: url:PATCH|/api/v1/accounts/:account_id/grading_period_sets/:id

Update an existing grading period set

204 No Content response code is returned if the update was successful.

Request Parameters:

Parameter Type Description
enrollment_term_ids[] Array

A list of associated term ids for the grading period set

grading_period_set[][title] Required string

The title of the grading period set

grading_period_set[][weighted] boolean

A boolean to determine whether the grading periods in the set are weighted

grading_period_set[][display_totals_for_all_grading_periods] boolean

A boolean to determine whether the totals for all grading periods in the set are displayed

Delete a grading period set GradingPeriodSetsController#destroy

DELETE /api/v1/accounts/:account_id/grading_period_sets/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/grading_period_sets/:id

204 No Content response code is returned if the deletion was successful.

List grading periods GradingPeriodsController#index

GET /api/v1/accounts/:account_id/grading_periods

Scope: url:GET|/api/v1/accounts/:account_id/grading_periods

GET /api/v1/courses/:course_id/grading_periods

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

Returns the paginated list of grading periods for the current course.

Example Response:

{
  "grading_periods": [GradingPeriod]
}

Get a single grading period GradingPeriodsController#show

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

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

Returns the grading period with the given id

Example Response:

{
  "grading_periods": [GradingPeriod]
}

Update a single grading period GradingPeriodsController#update

PUT /api/v1/courses/:course_id/grading_periods/:id

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

Update an existing grading period.

Request Parameters:

Parameter Type Description
grading_periods[][start_date] Required Date

The date the grading period starts.

grading_periods[][end_date] Required Date

no description

grading_periods[][weight] number

A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade

Example Response:

{
  "grading_periods": [GradingPeriod]
}

Delete a grading period GradingPeriodsController#destroy

DELETE /api/v1/courses/:course_id/grading_periods/:id

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

DELETE /api/v1/accounts/:account_id/grading_periods/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/grading_periods/:id

204 No Content response code is returned if the deletion was successful.

Batch update grading periods GradingPeriodsController#batch_update

PATCH /api/v1/courses/:course_id/grading_periods/batch_update

Scope: url:PATCH|/api/v1/courses/:course_id/grading_periods/batch_update

PATCH /api/v1/grading_period_sets/:set_id/grading_periods/batch_update

Scope: url:PATCH|/api/v1/grading_period_sets/:set_id/grading_periods/batch_update

Update multiple grading periods

Request Parameters:

Parameter Type Description
set_id Required string

The id of the grading period set.

grading_periods[][id] string

The id of the grading period. If the id parameter does not exist, a new grading period will be created.

grading_periods[][title] Required string

The title of the grading period. The title is required for creating a new grading period, but not for updating an existing grading period.

grading_periods[][start_date] Required Date

The date the grading period starts. The start_date is required for creating a new grading period, but not for updating an existing grading period.

grading_periods[][end_date] Required Date

The date the grading period ends. The end_date is required for creating a new grading period, but not for updating an existing grading period.

grading_periods[][close_date] Required Date

The date after which grades can no longer be changed for a grading period. The close_date is required for creating a new grading period, but not for updating an existing grading period.

grading_periods[][weight] number

A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade

Example Response:

{
  "grading_periods": [GradingPeriod]
}

Create a new grading standard GradingStandardsApiController#create

POST /api/v1/accounts/:account_id/grading_standards

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

POST /api/v1/courses/:course_id/grading_standards

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

Create a new grading standard

Request Parameters:

Parameter Type Description
title Required string

The title for the Grading Standard.

points_based boolean

Whether or not a grading scheme is points based. Defaults to false.

scaling_factor integer

The factor by which to scale a percentage into a points based scheme grade. This is the maximum number of points possible in the grading scheme. Defaults to 1. Not required for percentage based grading schemes.

grading_scheme_entry[][name] Required string

The name for an entry value within a GradingStandard that describes the range of the value e.g. A-

grading_scheme_entry[][value] Required integer

The value for the name of the entry within a GradingStandard. The entry represents the lower bound of the range for the entry. This range includes the value up to the next entry in the GradingStandard, or 100 if there is no upper bound. The lowest value will have a lower bound range of 0. e.g. 93

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/grading_standards \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'title=New standard name' \
  -d 'points_based=false' \
  -d 'scaling_factor=1.0' \
  -d 'grading_scheme_entry[][name]=A' \
  -d 'grading_scheme_entry[][value]=94' \
  -d 'grading_scheme_entry[][name]=A-' \
  -d 'grading_scheme_entry[][value]=90' \
  -d 'grading_scheme_entry[][name]=B+' \
  -d 'grading_scheme_entry[][value]=87' \
  -d 'grading_scheme_entry[][name]=B' \
  -d 'grading_scheme_entry[][value]=84' \
  -d 'grading_scheme_entry[][name]=B-' \
  -d 'grading_scheme_entry[][value]=80' \
  -d 'grading_scheme_entry[][name]=C+' \
  -d 'grading_scheme_entry[][value]=77' \
  -d 'grading_scheme_entry[][name]=C' \
  -d 'grading_scheme_entry[][value]=74' \
  -d 'grading_scheme_entry[][name]=C-' \
  -d 'grading_scheme_entry[][value]=70' \
  -d 'grading_scheme_entry[][name]=D+' \
  -d 'grading_scheme_entry[][value]=67' \
  -d 'grading_scheme_entry[][name]=D' \
  -d 'grading_scheme_entry[][value]=64' \
  -d 'grading_scheme_entry[][name]=D-' \
  -d 'grading_scheme_entry[][value]=61' \
  -d 'grading_scheme_entry[][name]=F' \
  -d 'grading_scheme_entry[][value]=0'

Example Response:

{
  "title": "New standard name",
  "id": 1,
  "context_id": 1,
  "context_type": "Course",
  "grading_scheme": [
    {"name": "A", "value": 0.9},
    {"name": "B", "value": 0.8}
  ]
}
Returns a GradingStandard object

List the grading standards available in a context. GradingStandardsApiController#context_index

GET /api/v1/courses/:course_id/grading_standards

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

GET /api/v1/accounts/:account_id/grading_standards

Scope: url:GET|/api/v1/accounts/:account_id/grading_standards

Returns the paginated list of grading standards for the given context that are visible to the user.

Example Request:

curl https://<canvas>/api/v1/courses/1/grading_standards \
  -H 'Authorization: Bearer <token>'
Returns a list of GradingStandard objects

Get a single grading standard in a context. GradingStandardsApiController#context_show

GET /api/v1/courses/:course_id/grading_standards/:grading_standard_id

Scope: url:GET|/api/v1/courses/:course_id/grading_standards/:grading_standard_id

GET /api/v1/accounts/:account_id/grading_standards/:grading_standard_id

Scope: url:GET|/api/v1/accounts/:account_id/grading_standards/:grading_standard_id

Returns a grading standard for the given context that is visible to the user.

Example Request:

curl https://<canvas>/api/v1/courses/1/grading_standards/5 \
  -H 'Authorization: Bearer <token>'
Returns a GradingStandard object

List group categories for a context GroupCategoriesController#index

GET /api/v1/accounts/:account_id/group_categories

Scope: url:GET|/api/v1/accounts/:account_id/group_categories

GET /api/v1/courses/:course_id/group_categories

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

Returns a paginated list of group categories in a context. The list returned depends on the permissions of the current user and the specified collaboration state.

Request Parameters:

Parameter Type Description
collaboration_state string

Filter group categories by their collaboration state:

  • “all”: Return both collaborative and non-collaborative group categories

  • “collaborative”: Return only collaborative group categories (default)

  • “non_collaborative”: Return only non-collaborative group categories

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/group_categories \
     -H 'Authorization: Bearer <token>' \
     -d 'collaboration_state=all'
Returns a list of GroupCategory objects

Get a single group category GroupCategoriesController#show

GET /api/v1/group_categories/:group_category_id

Scope: url:GET|/api/v1/group_categories/:group_category_id

Returns the data for a single group category, or a 401 if the caller doesn’t have the rights to see it.

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \
     -H 'Authorization: Bearer <token>'
Returns a GroupCategory object

Create a Group Category GroupCategoriesController#create

POST /api/v1/accounts/:account_id/group_categories

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

POST /api/v1/courses/:course_id/group_categories

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

Create a new group category

Request Parameters:

Parameter Type Description
name Required string

Name of the group category

non_collaborative boolean

Can only be set by users with the Differentiated Tag Add permission

If set to true, groups in this category will be only be visible to users with the Differentiated Tag Manage permission.

self_signup string

Allow students to sign up for a group themselves (Course Only). valid values are:

“enabled”

allows students to self sign up for any group in course

“restricted”

allows students to self sign up only for groups in the same section null disallows self sign up

Allowed values: enabled, restricted

auto_leader string

Assigns group leaders automatically when generating and allocating students to groups Valid values are:

“first”

the first student to be allocated to a group is the leader

“random”

a random student from all members is chosen as the leader

Allowed values: first, random

group_limit integer

Limit the maximum number of users in each group (Course Only). Requires self signup.

sis_group_category_id string

The unique SIS identifier.

create_group_count integer

Create this number of groups (Course Only).

split_group_count string

(Deprecated) Create this number of groups, and evenly distribute students among them. not allowed with “enable_self_signup”. because the group assignment happens synchronously, it’s recommended that you instead use the assign_unassigned_members endpoint. (Course Only)

Example Request:

curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \
    -F 'name=Project Groups' \
    -H 'Authorization: Bearer <token>'
Returns a GroupCategory object

Bulk manage groups in category GroupCategoriesController#bulk_manage_groups

POST /api/v1/group_categories/:group_category_id/bulk_manage_groups

Scope: url:POST|/api/v1/group_categories/:group_category_id/bulk_manage_groups

Perform bulk operations on groups within a category

Request Parameters:

Parameter Type Description
operations Required Hash

A hash containing arrays of create/update/delete operations: {

"create": [
  { "name": "New Group A" },
  { "name": "New Group B" }
],
"update": [
  { "id": 123, "name": "Updated Group Name A" },
  { "id": 456, "name": "Updated Group Name B" }
],
"delete": [
  { "id": 789 },
  { "id": 101 }
]

}

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id>/bulk_manage_groups \
     -X POST \
     -H 'Authorization: Bearer <token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "operations": {
             "create": [{"name": "New Group"}],
             "update": [{"id": 123, "name": "Updated Group"}],
             "delete": [{"id": 456}]
           }
         }'
Returns a GroupCategory object

Import category groups GroupCategoriesController#import

POST /api/v1/group_categories/:group_category_id/import

Scope: url:POST|/api/v1/group_categories/:group_category_id/import

Create Groups in a Group Category through a CSV import

For more information on the format that’s expected here, please see the “Group Category CSV” section in the API docs.

Request Parameters:

Parameter Type Description
attachment string

There are two ways to post group category import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request.

‘attachment’ is required for multipart/form-data style posts. Assumed to be outcome data from a file upload form field named ‘attachment’.

Examples:

curl -F attachment=@<filename> -H "Authorization: Bearer <token>" \
    'https://<canvas>/api/v1/group_categories/<category_id>/import'

If you decide to do a raw post, you can skip the ‘attachment’ argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the ‘extension’ argument.

Examples:

curl -H 'Content-Type: text/csv' --data-binary @<filename>.csv \
    -H "Authorization: Bearer <token>" \
    'https://<canvas>/api/v1/group_categories/<category_id>/import'

Example Response:

# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "GroupCategory",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "course_group_import",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}
Returns a Progress object

Update a Group Category GroupCategoriesController#update

PUT /api/v1/group_categories/:group_category_id

Scope: url:PUT|/api/v1/group_categories/:group_category_id

Modifies an existing group category.

Request Parameters:

Parameter Type Description
name string

Name of the group category

self_signup string

Allow students to sign up for a group themselves (Course Only). Valid values are:

“enabled”

allows students to self sign up for any group in course

“restricted”

allows students to self sign up only for groups in the same section null disallows self sign up

Allowed values: enabled, restricted

auto_leader string

Assigns group leaders automatically when generating and allocating students to groups Valid values are:

“first”

the first student to be allocated to a group is the leader

“random”

a random student from all members is chosen as the leader

Allowed values: first, random

group_limit integer

Limit the maximum number of users in each group (Course Only). Requires self signup.

sis_group_category_id string

The unique SIS identifier.

create_group_count integer

Create this number of groups (Course Only).

split_group_count string

(Deprecated) Create this number of groups, and evenly distribute students among them. not allowed with “enable_self_signup”. because the group assignment happens synchronously, it’s recommended that you instead use the assign_unassigned_members endpoint. (Course Only)

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \
    -X PUT \
    -F 'name=Project Groups' \
    -H 'Authorization: Bearer <token>'
Returns a GroupCategory object

Delete a Group Category GroupCategoriesController#destroy

DELETE /api/v1/group_categories/:group_category_id

Scope: url:DELETE|/api/v1/group_categories/:group_category_id

Deletes a group category and all groups under it. Protected group categories can not be deleted, i.e. “communities” and “student_organized”.

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \
      -X DELETE \
      -H 'Authorization: Bearer <token>'

List groups in group category GroupCategoriesController#groups

GET /api/v1/group_categories/:group_category_id/groups

Scope: url:GET|/api/v1/group_categories/:group_category_id/groups

Returns a paginated list of groups in a group category

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \
     -H 'Authorization: Bearer <token>'
Returns a list of Group objects

export groups in and users in category GroupCategoriesController#export

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

GET /api/v1/group_categories/:group_category_id/export

Scope: url:GET|/api/v1/group_categories/:group_category_id/export

Returns a csv file of users in format ready to import.

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id>/export \
     -H 'Authorization: Bearer <token>'

List users in group category GroupCategoriesController#users

GET /api/v1/group_categories/:group_category_id/users

Scope: url:GET|/api/v1/group_categories/:group_category_id/users

Returns a paginated list of users in the group category.

Request Parameters:

Parameter Type Description
search_term string

The partial name or full ID of the users to match and return in the results list. Must be at least 3 characters.

unassigned boolean

Set this value to true if you wish only to search unassigned users in the group category.

Example Request:

curl https://<canvas>/api/v1/group_categories/1/users \
     -H 'Authorization: Bearer <token>'
Returns a list of User objects

Assign unassigned members GroupCategoriesController#assign_unassigned_members

POST /api/v1/group_categories/:group_category_id/assign_unassigned_members

Scope: url:POST|/api/v1/group_categories/:group_category_id/assign_unassigned_members

Assign all unassigned members as evenly as possible among the existing student groups.

Request Parameters:

Parameter Type Description
sync boolean

The assigning is done asynchronously by default. If you would like to override this and have the assigning done synchronously, set this value to true.

Example Request:

curl https://<canvas>/api/v1/group_categories/1/assign_unassigned_members \
     -H 'Authorization: Bearer <token>'

Example Response:

# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "GroupCategory",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "assign_unassigned_members",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}

# New Group Memberships (when sync = true)
[
  {
    "id": 65,
    "new_members": [
      {
        "user_id": 2,
        "name": "Sam",
        "display_name": "Sam",
        "sections": [
          {
            "section_id": 1,
            "section_code": "Section 1"
          }
        ]
      },
      {
        "user_id": 3,
        "name": "Sue",
        "display_name": "Sue",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      }
    ]
  },
  {
    "id": 66,
    "new_members": [
      {
        "user_id": 5,
        "name": "Joe",
        "display_name": "Joe",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      },
      {
        "user_id": 11,
        "name": "Cecil",
        "display_name": "Cecil",
        "sections": [
          {
            "section_id": 3,
            "section_code": "Section 3"
          }
        ]
      }
    ]
  }
]

List your groups GroupsController#index

GET /api/v1/users/self/groups

Scope: url:GET|/api/v1/users/self/groups

Returns a paginated list of active groups for the current user.

Request Parameters:

Parameter Type Description
context_type string

Only include groups that are in this type of context.

Allowed values: Account, Course

include[] string
  • “tabs”: Include the list of tabs configured for each group. See the List available tabs API for more information.

Allowed values: tabs

Example Request:

curl https://<canvas>/api/v1/users/self/groups?context_type=Account \
     -H 'Authorization: Bearer <token>'
Returns a list of Group objects

List the groups available in a context. GroupsController#context_index

GET /api/v1/accounts/:account_id/groups

Scope: url:GET|/api/v1/accounts/:account_id/groups

GET /api/v1/courses/:course_id/groups

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

Returns the paginated list of active groups in the given context that are visible to user.

Request Parameters:

Parameter Type Description
only_own_groups boolean

Will only include groups that the user belongs to if this is set

include[] string
  • “tabs”: Include the list of tabs configured for each group. See the List available tabs API for more information.

Allowed values: tabs

collaboration_state string

Filter groups by their collaboration state:

  • “all”: Return both collaborative and non-collaborative groups

  • “collaborative”: Return only collaborative groups (default)

  • “non_collaborative”: Return only non-collaborative groups

Example Request:

curl https://<canvas>/api/v1/courses/1/groups \
     -H 'Authorization: Bearer <token>'
Returns a list of Group objects

Get a single group GroupsController#show

GET /api/v1/groups/:group_id

Scope: url:GET|/api/v1/groups/:group_id

Returns the data for a single group, or a 401 if the caller doesn’t have the rights to see it.

Request Parameters:

Parameter Type Description
include[] string
  • “permissions”: Include permissions the current user has for the group.

  • “tabs”: Include the list of tabs configured for each group. See the List available tabs API for more information.

Allowed values: permissions, tabs

Example Request:

curl https://<canvas>/api/v1/groups/<group_id> \
     -H 'Authorization: Bearer <token>'
Returns a Group object