All API Resources
Show an access token TokensController#show
GET /api/v1/users/:user_id/tokens/:id
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
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
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
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
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>'
Get a single account calendar AccountCalendarsApiController#show
GET /api/v1/account_calendars/:account_id
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>'
Update a calendar AccountCalendarsApiController#update
PUT /api/v1/account_calendars/:account_id
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'
Update several calendars AccountCalendarsApiController#bulk_update
PUT /api/v1/accounts/:account_id/account_calendars
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
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: |
Example Request:
curl https://<canvas>/api/v1/accounts/1/account_calendars \
-H 'Authorization: Bearer <token>'
Count of all visible account calendars AccountCalendarsApiController#visible_calendars_count
GET /api/v1/accounts/:account_id/visible_calendars_count
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
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
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
Show a global notification AccountNotificationsController#show
GET /api/v1/accounts/:account_id/account_notifications/:id
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
Close notification for user AccountNotificationsController#user_close_notification
DELETE /api/v1/accounts/:account_id/account_notifications/:id
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
Create a global notification AccountNotificationsController#create
POST /api/v1/accounts/:account_id/account_notifications
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: |
|
account_notification_roles[] | string |
The role(s) to send global notification to. Note: ommitting this field will send to everyone Example:
|
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
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: |
|
account_notification_roles[] | string |
The role(s) to send global notification to. Note: ommitting this field will send to everyone Example:
|
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
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
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'
Index of Reports AccountReportsController#index
GET /api/v1/accounts/:account_id/reports/:report
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>
Status of a Report AccountReportsController#show
GET /api/v1/accounts/:account_id/reports/:report/:id
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>
Delete a Report AccountReportsController#destroy
DELETE /api/v1/accounts/:account_id/reports/:report/:id
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>
Abort a Report AccountReportsController#abort
PUT /api/v1/accounts/:account_id/reports/:report/:id/abort
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
List accounts AccountsController#index
GET /api/v1/accounts
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.
Allowed values: |
Get accounts that admins can manage AccountsController#manageable_accounts
GET /api/v1/manageable_accounts
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 objectsGet accounts that users can create courses in AccountsController#course_creation_accounts
GET /api/v1/course_creation_accounts
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 objectsList accounts for course admins AccountsController#course_accounts
GET /api/v1/course_accounts
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 objectsGet a single account AccountsController#show
GET /api/v1/accounts/:id
url:GET|/api/v1/accounts/:id
Retrieve information on an individual account, given by id or sis sis_account_id.
Returns an Account objectSettings AccountsController#show_settings
GET /api/v1/accounts/:account_id/settings
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
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
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
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.
Allowed values: |
Example Request:
curl https://<canvas>/api/v1/accounts/<account_id>/sub_accounts \
-H 'Authorization: Bearer <token>'
Get the Terms of Service AccountsController#terms_of_service
GET /api/v1/accounts/:account_id/terms_of_service
url:GET|/api/v1/accounts/:account_id/terms_of_service
Returns the terms of service for that account
Returns a TermsOfService objectGet help links AccountsController#help_links
GET /api/v1/accounts/:account_id/help_links
url:GET|/api/v1/accounts/:account_id/help_links
Returns the help links for that account
Returns a HelpLinks objectGet the manually-created courses sub-account for the domain root account AccountsController#manually_created_courses_account
GET /api/v1/manually_created_courses_account
url:GET|/api/v1/manually_created_courses_account
List active courses in an account AccountsController#courses_api
GET /api/v1/accounts/:account_id/courses
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: |
|
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: |
|
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 |
Allowed values: |
|
sort | string |
The column to sort results by.
Allowed values: |
|
order | string |
The order to sort the given column by.
Allowed values: |
|
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: |
|
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. |
Update an account AccountsController#update
PUT /api/v1/accounts/:id
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
Required feature option:
|
|
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 |
|
|
account[lock_outcome_proficiency][locked] | boolean |
|
|
account[settings][lock_proficiency_calculation][value] | boolean |
|
|
account[lock_proficiency_calculation][locked] | boolean |
|
|
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'
Delete a user from the root account AccountsController#remove_user
DELETE /api/v1/accounts/:account_id/users/:user_id
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
Restore a deleted user from a root account AccountsController#restore_user
PUT /api/v1/accounts/:account_id/users/:user_id/restore
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
Create a new sub-account SubAccountsController#create
POST /api/v1/accounts/:account_id/sub_accounts
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. |
Delete a sub-account SubAccountsController#destroy
DELETE /api/v1/accounts/:account_id/sub_accounts/:id
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 objectGet account Lti::AccountLookupController#show
GET /api/lti/accounts/:account_id
url:GET|/api/lti/accounts/:account_id
Retrieve information on an individual account, given by local or global ID.
Returns an Account objectMake an account admin AdminsController#create
POST /api/v1/accounts/:account_id/admins
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 |
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. |
Remove account admin AdminsController#destroy
DELETE /api/v1/accounts/:account_id/admins/:user_id
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 |
|
|
role_id | Required | integer |
The id of the role representing the user’s admin relationship with the account. |
List account admins AdminsController#index
GET /api/v1/accounts/:account_id/admins
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. |
List my admin roles AdminsController#self_roles
GET /api/v1/accounts/:account_id/admins/self
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.
Get department-level participation data
GET /api/v1/accounts/:account_id/analytics/terms/:term_id/activity
url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/activity
GET /api/v1/accounts/:account_id/analytics/current/activity
url:GET|/api/v1/accounts/:account_id/analytics/current/activity
GET /api/v1/accounts/:account_id/analytics/completed/activity
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
url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/grades
GET /api/v1/accounts/:account_id/analytics/current/grades
url:GET|/api/v1/accounts/:account_id/analytics/current/grades
GET /api/v1/accounts/:account_id/analytics/completed/grades
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
url:GET|/api/v1/accounts/:account_id/analytics/terms/:term_id/statistics
GET /api/v1/accounts/:account_id/analytics/current/statistics
url:GET|/api/v1/accounts/:account_id/analytics/current/statistics
GET /api/v1/accounts/:account_id/analytics/completed/statistics
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
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
url:GET|/api/v1/accounts/:account_id/analytics/current/statistics_by_subaccount
GET /api/v1/accounts/:account_id/analytics/completed/statistics_by_subaccount
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
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
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
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: |
|
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
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
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
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
url:GET|/api/v1/courses/:course_id/external_feeds
GET /api/v1/groups/:group_id/external_feeds
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>'
Create an external feed ExternalFeedsController#create
POST /api/v1/courses/:course_id/external_feeds
url:POST|/api/v1/courses/:course_id/external_feeds
POST /api/v1/groups/:group_id/external_feeds
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: |
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>'
Delete an external feed ExternalFeedsController#destroy
DELETE /api/v1/courses/:course_id/external_feeds/:external_feed_id
url:DELETE|/api/v1/courses/:course_id/external_feeds/:external_feed_id
DELETE /api/v1/groups/:group_id/external_feeds/:external_feed_id
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>'
List announcements AnnouncementsApiController#index
GET /api/v1/announcements
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, |
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:
|
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",
...
}]
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
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: |
List appointment groups AppointmentGroupsController#index
GET /api/v1/appointment_groups
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: |
|
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.
Allowed values: |
Create an appointment group AppointmentGroupsController#create
POST /api/v1/appointment_groups
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 |
Allowed values: |
|
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
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.
Allowed values: |
Update an appointment group AppointmentGroupsController#update
PUT /api/v1/appointment_groups/:id
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 |
Allowed values: |
|
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
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
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: |
List student group participants AppointmentGroupsController#groups
GET /api/v1/appointment_groups/:id/groups
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: |
Get next appointment AppointmentGroupsController#next_appointment
GET /api/v1/appointment_groups/next_appointment
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. |
Set extensions for student assignment submissions AssignmentExtensionsController#create
POST /api/v1/courses/:course_id/assignments/:assignment_id/extensions
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
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: |
|
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: |
|
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.) |
Get an Assignment Group AssignmentGroupsApiController#show
GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id
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: |
|
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) |
Create an Assignment Group AssignmentGroupsApiController#create
POST /api/v1/courses/:course_id/assignment_groups
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 |
Edit an Assignment Group AssignmentGroupsApiController#update
PUT /api/v1/courses/:course_id/assignment_groups/:assignment_group_id
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 |
Destroy an Assignment Group AssignmentGroupsApiController#destroy
DELETE /api/v1/courses/:course_id/assignment_groups/:assignment_group_id
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. |
Delete an assignment AssignmentsController#destroy
DELETE /api/v1/courses/:course_id/assignments/:id
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>'
List assignments AssignmentsApiController#index
GET /api/v1/courses/:course_id/assignments
url:GET|/api/v1/courses/:course_id/assignments
GET /api/v1/courses/:course_id/assignment_groups/:assignment_group_id/assignments
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:
Allowed values: |
|
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: |
|
assignment_ids[] | string |
if set, return only assignments specified |
|
order_by | string |
Determines the order of the assignments. Defaults to “position”.
Allowed values: |
|
post_to_sis | boolean |
Return only assignments that have post_to_sis set or not set. |
|
new_quizzes | boolean |
Return only New Quizzes assignments |
List assignments for user AssignmentsApiController#user_index
GET /api/v1/users/:user_id/courses/:course_id/assignments
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
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: |
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
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
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
Get a single assignment AssignmentsApiController#show
GET /api/v1/courses/:course_id/assignments/:id
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: |
|
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 |
Create an assignment AssignmentsApiController#create
POST /api/v1/courses/:course_id/assignments
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:
If you are allowing online submissions, you can have one or many allowed submission types:
Allowed values: |
|
assignment[allowed_extensions][] | string |
Allowed extensions if submission_types includes “online_upload” Example:
|
|
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: |
|
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”. |
Edit an assignment AssignmentsApiController#update
PUT /api/v1/courses/:course_id/assignments/:id
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:
If you are allowing online submissions, you can have one or many allowed submission types:
Allowed values: |
||
assignment[allowed_extensions][] | string |
Allowed extensions if submission_types includes “online_upload” Example:
|
||
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: |
||
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[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. |
Bulk update assignment dates AssignmentsApiController#bulk_update
PUT /api/v1/courses/:course_id/assignments/bulk_update
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>"
List assignment overrides AssignmentOverridesController#index
GET /api/v1/courses/:course_id/assignments/:assignment_id/overrides
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 objectsGet a single assignment override AssignmentOverridesController#show
GET /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id
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 objectRedirect to the assignment override for a group AssignmentOverridesController#group_alias
GET /api/v1/groups/:group_id/assignments/:assignment_id/override
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
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
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:
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>"
Update an assignment override AssignmentOverridesController#update
PUT /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id
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>"
Delete an assignment override AssignmentOverridesController#destroy
DELETE /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id
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>"
Batch retrieve overrides in a course AssignmentOverridesController#batch_retrieve
GET /api/v1/courses/:course_id/assignments/overrides
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>"
Batch create overrides in a course AssignmentOverridesController#batch_create
POST /api/v1/courses/:course_id/assignments/overrides
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>"
Batch update overrides in a course AssignmentOverridesController#batch_update
PUT /api/v1/courses/:course_id/assignments/overrides
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>"
List authentication providers AuthenticationProvidersController#index
GET /api/v1/accounts/:account_id/authentication_providers
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>'
Get authentication provider AuthenticationProvidersController#show
GET /api/v1/accounts/:account_id/authentication_providers/:id
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>'
Update authentication provider AuthenticationProvidersController#update
PUT /api/v1/accounts/:account_id/authentication_providers/:id
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>'
Delete authentication provider AuthenticationProvidersController#destroy
DELETE /api/v1/accounts/:account_id/authentication_providers/:id
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
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>'
show account auth settings AuthenticationProvidersController#show_sso_settings
GET /api/v1/accounts/:account_id/sso_settings
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>'
update account auth settings AuthenticationProvidersController#update_sso_settings
PUT /api/v1/accounts/:account_id/sso_settings
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>'
Query by login. AuthenticationAuditApiController#for_login
GET /api/v1/audit/authentication/logins/:login_id
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
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
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
url:GET|/api/v1/courses/:course_id/blackout_dates
GET /api/v1/accounts/:account_id/blackout_dates
url:GET|/api/v1/accounts/:account_id/blackout_dates
Returns the list of blackout dates for the current context.
Returns a list of BlackoutDate objectsGet a single blackout date BlackoutDatesController#show
GET /api/v1/courses/:course_id/blackout_dates/:id
url:GET|/api/v1/courses/:course_id/blackout_dates/:id
GET /api/v1/accounts/:account_id/blackout_dates/:id
url:GET|/api/v1/accounts/:account_id/blackout_dates/:id
Returns the blackout date with the given id.
Returns a BlackoutDate objectNew Blackout Date BlackoutDatesController#new
GET /api/v1/courses/:course_id/blackout_dates/new
url:GET|/api/v1/courses/:course_id/blackout_dates/new
GET /api/v1/accounts/:account_id/blackout_dates/new
url:GET|/api/v1/accounts/:account_id/blackout_dates/new
Initialize an unsaved Blackout Date for the given context.
Returns a BlackoutDate objectCreate Blackout Date BlackoutDatesController#create
POST /api/v1/courses/:course_id/blackout_dates
url:POST|/api/v1/courses/:course_id/blackout_dates
POST /api/v1/accounts/:account_id/blackout_dates
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. |
Update Blackout Date BlackoutDatesController#update
PUT /api/v1/courses/:course_id/blackout_dates/:id
url:PUT|/api/v1/courses/:course_id/blackout_dates/:id
PUT /api/v1/accounts/:account_id/blackout_dates/:id
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. |
Delete Blackout Date BlackoutDatesController#destroy
DELETE /api/v1/courses/:course_id/blackout_dates/:id
url:DELETE|/api/v1/courses/:course_id/blackout_dates/:id
DELETE /api/v1/accounts/:account_id/blackout_dates/:id
url:DELETE|/api/v1/accounts/:account_id/blackout_dates/:id
Delete a blackout date for the given context.
Returns a BlackoutDate objectUpdate a list of Blackout Dates BlackoutDatesController#bulk_update
PUT /api/v1/courses/:course_id/blackout_dates
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 |
|
List block templates BlockEditorTemplatesApiController#index
GET /api/v1/courses/:course_id/block_editor_templates
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: |
|
order | string |
The sorting order. Defaults to ‘asc’.
Allowed values: |
|
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: |
|
include[] | string |
no description
Allowed values: |
Example Request:
curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/block_editor_templates?sort=name&order=asc&drafts=true
Get blueprint information MasterCourses::MasterTemplatesController#show
GET /api/v1/courses/:course_id/blueprint_templates/:template_id
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>'
Get associated course information MasterCourses::MasterTemplatesController#associated_courses
GET /api/v1/courses/:course_id/blueprint_templates/:template_id/associated_courses
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>'
Update associated courses MasterCourses::MasterTemplatesController#update_associations
PUT /api/v1/courses/:course_id/blueprint_templates/:template_id/update_associations
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
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>'
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
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 |
|
|
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
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.
List blueprint migrations MasterCourses::MasterTemplatesController#migrations_index
GET /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations
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>'
Show a blueprint migration MasterCourses::MasterTemplatesController#migrations_show
GET /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations/:id
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>'
Get migration details MasterCourses::MasterTemplatesController#migration_details
GET /api/v1/courses/:course_id/blueprint_templates/:template_id/migrations/:id/details
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>'
List blueprint subscriptions MasterCourses::MasterTemplatesController#subscriptions_index
GET /api/v1/courses/:course_id/blueprint_subscriptions
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>'
List blueprint imports MasterCourses::MasterTemplatesController#imports_index
GET /api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations
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>'
Show a blueprint import MasterCourses::MasterTemplatesController#imports_show
GET /api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations/:id
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>'
Get import details MasterCourses::MasterTemplatesController#import_details
GET /api/v1/courses/:course_id/blueprint_subscriptions/:subscription_id/migrations/:id/details
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>'
List bookmarks Bookmarks::BookmarksController#index
GET /api/v1/users/self/bookmarks
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>'
Create bookmark Bookmarks::BookmarksController#create
POST /api/v1/users/self/bookmarks
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>'
Get bookmark Bookmarks::BookmarksController#show
GET /api/v1/users/self/bookmarks/:id
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>'
Update bookmark Bookmarks::BookmarksController#update
PUT /api/v1/users/self/bookmarks/:id
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>'
Delete bookmark Bookmarks::BookmarksController#destroy
DELETE /api/v1/users/self/bookmarks/:id
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
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
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: |
|
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. |
List calendar events for a user CalendarEventsApiController#user_index
GET /api/v1/users/:user_id/calendar_events
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: |
|
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. |
Create a calendar event CalendarEventsApiController#create
POST /api/v1/calendar_events
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: |
|
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
url:GET|/api/v1/calendar_events/:id
Reserve a time slot CalendarEventsApiController#reserve
POST /api/v1/calendar_events/:id/reservations
url:POST|/api/v1/calendar_events/:id/reservations
POST /api/v1/calendar_events/:id/reservations/:participant_id
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
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: |
|
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
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: |
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
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
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
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
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
url:GET|/api/v1/courses/:course_id/collaborations
GET /api/v1/groups/:group_id/collaborations
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
url:GET|/api/v1/collaborations/:id/members
A paginated list of the collaborators of a given collaboration
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
include[] | string |
Allowed values: |
Example Request:
curl https://<canvas>/api/v1/courses/1/collaborations/1/members
List potential members CollaborationsController#potential_collaborators
GET /api/v1/courses/:course_id/potential_collaborators
url:GET|/api/v1/courses/:course_id/potential_collaborators
GET /api/v1/groups/:group_id/potential_collaborators
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 objectsList of CommMessages for a user CommMessagesApiController#index
GET /api/v1/comm_messages
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. |
List user communication channels CommunicationChannelsController#index
GET /api/v1/users/:user_id/communication_channels
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>'
Create a communication channel CommunicationChannelsController#create
POST /api/v1/users/:user_id/communication_channels
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: |
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' \
Delete a communication channel CommunicationChannelsController#destroy
DELETE /api/v1/users/:user_id/communication_channels/:id
url:DELETE|/api/v1/users/:user_id/communication_channels/:id
DELETE /api/v1/users/:user_id/communication_channels/:type/:address
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
Delete a push notification endpoint CommunicationChannelsController#delete_push_token
DELETE /api/v1/users/self/communication_channels/push
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
url:GET|/api/v1/courses/:course_id/conferences
GET /api/v1/groups/:group_id/conferences
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>"
List conferences for the current user ConferencesController#for_user
GET /api/v1/conferences
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>"
List content exports ContentExportsApiController#index
GET /api/v1/courses/:course_id/content_exports
url:GET|/api/v1/courses/:course_id/content_exports
GET /api/v1/groups/:group_id/content_exports
url:GET|/api/v1/groups/:group_id/content_exports
GET /api/v1/users/:user_id/content_exports
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 objectsShow content export ContentExportsApiController#show
GET /api/v1/courses/:course_id/content_exports/:id
url:GET|/api/v1/courses/:course_id/content_exports/:id
GET /api/v1/groups/:group_id/content_exports/:id
url:GET|/api/v1/groups/:group_id/content_exports/:id
GET /api/v1/users/:user_id/content_exports/:id
url:GET|/api/v1/users/:user_id/content_exports/:id
Get information about a single content export.
Returns a ContentExport objectExport content ContentExportsApiController#create
POST /api/v1/courses/:course_id/content_exports
url:POST|/api/v1/courses/:course_id/content_exports
POST /api/v1/groups/:group_id/content_exports
url:POST|/api/v1/groups/:group_id/content_exports
POST /api/v1/users/:user_id/content_exports
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 |
Allowed values: |
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.
Allowed values: |
List migration issues MigrationIssuesController#index
GET /api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues
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
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
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
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>'
Get a migration issue MigrationIssuesController#show
GET /api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues/:id
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
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
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
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>'
Update a migration issue MigrationIssuesController#update
PUT /api/v1/accounts/:account_id/content_migrations/:content_migration_id/migration_issues/:id
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
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
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
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: |
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'
List content migrations ContentMigrationsController#index
GET /api/v1/accounts/:account_id/content_migrations
url:GET|/api/v1/accounts/:account_id/content_migrations
GET /api/v1/courses/:course_id/content_migrations
url:GET|/api/v1/courses/:course_id/content_migrations
GET /api/v1/groups/:group_id/content_migrations
url:GET|/api/v1/groups/:group_id/content_migrations
GET /api/v1/users/:user_id/content_migrations
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>'
Get a content migration ContentMigrationsController#show
GET /api/v1/accounts/:account_id/content_migrations/:id
url:GET|/api/v1/accounts/:account_id/content_migrations/:id
GET /api/v1/courses/:course_id/content_migrations/:id
url:GET|/api/v1/courses/:course_id/content_migrations/:id
GET /api/v1/groups/:group_id/content_migrations/:id
url:GET|/api/v1/groups/:group_id/content_migrations/:id
GET /api/v1/users/:user_id/content_migrations/:id
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>'
Create a content migration ContentMigrationsController#create
POST /api/v1/accounts/:account_id/content_migrations
url:POST|/api/v1/accounts/:account_id/content_migrations
POST /api/v1/courses/:course_id/content_migrations
url:POST|/api/v1/courses/:course_id/content_migrations
POST /api/v1/groups/:group_id/content_migrations
url:POST|/api/v1/groups/:group_id/content_migrations
POST /api/v1/users/:user_id/content_migrations
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:
-
POST to create
-
Use the Progress specified in progress_url to monitor progress
For file uploading:
-
POST to create with file info in pre_attachment
-
Do file upload processing using the data in the pre_attachment data
-
GET the ContentMigration
-
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
Allowed values: |
|
settings[insert_into_module_position] | integer |
The (1-based) position to insert the imported items into the course (if |
|
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: |
|
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 |
|
select | Hash |
For
Allowed values: |
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>'
Update a content migration ContentMigrationsController#update
PUT /api/v1/accounts/:account_id/content_migrations/:id
url:PUT|/api/v1/accounts/:account_id/content_migrations/:id
PUT /api/v1/courses/:course_id/content_migrations/:id
url:PUT|/api/v1/courses/:course_id/content_migrations/:id
PUT /api/v1/groups/:group_id/content_migrations/:id
url:PUT|/api/v1/groups/:group_id/content_migrations/:id
PUT /api/v1/users/:user_id/content_migrations/:id
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 objectList Migration Systems ContentMigrationsController#available_migrators
GET /api/v1/accounts/:account_id/content_migrations/migrators
url:GET|/api/v1/accounts/:account_id/content_migrations/migrators
GET /api/v1/courses/:course_id/content_migrations/migrators
url:GET|/api/v1/courses/:course_id/content_migrations/migrators
GET /api/v1/groups/:group_id/content_migrations/migrators
url:GET|/api/v1/groups/:group_id/content_migrations/migrators
GET /api/v1/users/:user_id/content_migrations/migrators
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 objectsList items for selective import ContentMigrationsController#content_list
GET /api/v1/accounts/:account_id/content_migrations/:id/selective_data
url:GET|/api/v1/accounts/:account_id/content_migrations/:id/selective_data
GET /api/v1/courses/:course_id/content_migrations/:id/selective_data
url:GET|/api/v1/courses/:course_id/content_migrations/:id/selective_data
GET /api/v1/groups/:group_id/content_migrations/:id/selective_data
url:GET|/api/v1/groups/:group_id/content_migrations/:id/selective_data
GET /api/v1/users/:user_id/content_migrations/:id/selective_data
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: |
Get asset id mapping ContentMigrationsController#asset_id_mapping
GET /api/v1/courses/:course_id/content_migrations/:id/asset_id_mapping
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
url:GET|/api/v1/courses/:course_id/csp_settings
GET /api/v1/accounts/:account_id/csp_settings
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
url:PUT|/api/v1/courses/:course_id/csp_settings
PUT /api/v1/accounts/:account_id/csp_settings
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: |
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
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
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
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
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
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: |
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
List content shares ContentSharesController#index
GET /api/v1/users/:user_id/content_shares/sent
url:GET|/api/v1/users/:user_id/content_shares/sent
GET /api/v1/users/:user_id/content_shares/received
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'
Get unread shares count ContentSharesController#unread_count
GET /api/v1/users/:user_id/content_shares/unread_count
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
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'
Remove content share ContentSharesController#destroy
DELETE /api/v1/users/:user_id/content_shares/:id
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
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'
Update a content share ContentSharesController#update
PUT /api/v1/users/:user_id/content_shares/:id
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: |
Example Request:
curl -X PUT 'https://<canvas>/api/v1/users/self/content_shares/123?read_state=read'
List conversations ConversationsController#index
GET /api/v1/conversations
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: |
|
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: |
|
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 |
Allowed values: |
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"
}
]
Create a conversation ConversationsController#create
POST /api/v1/conversations
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: |
|
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: |
|
scope | string |
Used when generating “visible” in the API response. See the explanation under the index API action
Allowed values: |
|
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: |
|
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
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
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: |
|
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: |
|
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
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: |
|
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: |
|
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: |
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
url:POST|/api/v1/conversations/mark_all_as_read
Mark all conversations as read.
Delete a conversation ConversationsController#destroy
DELETE /api/v1/conversations/:id
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
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
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: |
|
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
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
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: |
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'
Find recipients ConversationsController#find_recipients
GET /api/v1/conversations/find_recipients
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
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
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. |
Query by account. CourseAuditApiController#for_account
GET /api/v1/audit/course/accounts/:account_id
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. |
Show a Course pace CoursePacesController#api_show
GET /api/v1/courses/:course_id/course_pacing/:id
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>'
Create a Course pace CoursePacesController#create
POST /api/v1/courses/:course_id/course_pacing
url:POST|/api/v1/courses/:course_id/course_pacing
Update a Course pace CoursePacesController#update
PUT /api/v1/courses/:course_id/course_pacing/:id
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 |
|
|
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>'
Delete a Course pace CoursePacesController#destroy
DELETE /api/v1/courses/:course_id/course_pacing/:id
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>'
Set extensions for student quiz submissions Quizzes::CourseQuizExtensionsController#create
POST /api/v1/courses/:course_id/quiz_extensions
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
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: |
|
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: |
|
exclude_blueprint_courses | boolean |
When set, only return courses that are not configured as blueprint courses. |
|
include[] | string |
Allowed values: |
|
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: |
List courses for a user CoursesController#user_index
GET /api/v1/users/:user_id/courses
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 |
Allowed values: |
|
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: |
|
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: |
|
homeroom | boolean |
If set, only return homeroom courses. |
|
account_id | string |
If set, only include courses associated with this account |
Get user progress CoursesController#user_progress
GET /api/v1/courses/:course_id/users/:user_id/progress
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.
Create a new course CoursesController#create
POST /api/v1/accounts/:account_id/courses
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):
|
|
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
other types may be added in the future
Allowed values: |
|
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. |
Upload a file CoursesController#create_file
POST /api/v1/courses/:course_id/files
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
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 objectsList users in course CoursesController#users
GET /api/v1/courses/:course_id/users
url:GET|/api/v1/courses/:course_id/users
GET /api/v1/courses/:course_id/search_users
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: |
|
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: |
|
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 |
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.
if present. Default is to not include Test Student.
such as analytics information
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.
Allowed values: |
|
user_id | string |
If this parameter is given and it corresponds to a user in the course, the |
|
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: |
List recently logged in students CoursesController#recent_students
GET /api/v1/courses/:course_id/recent_students
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
Get single user CoursesController#user
GET /api/v1/courses/:course_id/users/:id
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 objectSearch for content share users CoursesController#content_share_users
GET /api/v1/courses/:course_id/content_share_users
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'
Preview processed html CoursesController#preview_html
POST /api/v1/courses/:course_id/preview_html
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
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
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
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
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: |
Example Response:
{ "delete": "true" }
Get course settings CoursesController#api_settings
GET /api/v1/courses/:course_id/settings
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
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
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>'
Get a single course CoursesController#show
GET /api/v1/courses/:id
url:GET|/api/v1/courses/:id
GET /api/v1/accounts/:account_id/courses/:id
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 |
Allowed values: |
|
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. |
Update a course CoursesController#update
PUT /api/v1/courses/:id
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):
|
|
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.
Allowed values: |
|
course[default_view] | string |
The type of page that users will see when they first visit the course
other types may be added in the future
Allowed values: |
|
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 |
|
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[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.
|
|
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
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’.
Allowed values: |
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'
Reset a course CoursesController#reset_content
POST /api/v1/courses/:course_id/reset_content
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 objectGet effective due dates CoursesController#effective_due_dates
GET /api/v1/courses/:course_id/effective_due_dates
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
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
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
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
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
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: |
|
only[] | string |
A list of the course content types to copy, all areas not listed will not be copied.
Allowed values: |
List custom gradebook columns CustomGradebookColumnsApiController#index
GET /api/v1/courses/:course_id/custom_gradebook_columns
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) |
Create a custom gradebook column CustomGradebookColumnsApiController#create
POST /api/v1/courses/:course_id/custom_gradebook_columns
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 |
Update a custom gradebook column CustomGradebookColumnsApiController#update
PUT /api/v1/courses/:course_id/custom_gradebook_columns/:id
url:PUT|/api/v1/courses/:course_id/custom_gradebook_columns/:id
Accepts the same parameters as custom gradebook column creation
Returns a CustomColumn objectDelete a custom gradebook column CustomGradebookColumnsApiController#destroy
DELETE /api/v1/courses/:course_id/custom_gradebook_columns/:id
url:DELETE|/api/v1/courses/:course_id/custom_gradebook_columns/:id
Permanently deletes a custom column and its associated data
Returns a CustomColumn objectReorder custom columns CustomGradebookColumnsApiController#reorder
POST /api/v1/courses/:course_id/custom_gradebook_columns/reorder
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
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. |
Update column data CustomGradebookColumnDataApiController#update
PUT /api/v1/courses/:course_id/custom_gradebook_columns/:id/data/:user_id
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. |
Bulk update column data CustomGradebookColumnDataApiController#bulk_update
PUT /api/v1/courses/:course_id/custom_gradebook_column_data
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:
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
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”. |
List Developer Keys DeveloperKeysController#index
GET /api/v1/accounts/:account_id/developer_keys
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). |
Create a Developer Key DeveloperKeysController#create
POST /api/v1/accounts/:account_id/developer_keys
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. |
Update a Developer Key DeveloperKeysController#update
PUT /api/v1/developer_keys/:id
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. |
Delete a Developer Key DeveloperKeysController#destroy
DELETE /api/v1/developer_keys/:id
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 objectList discussion topics DiscussionTopicsController#index
GET /api/v1/courses/:course_id/discussion_topics
url:GET|/api/v1/courses/:course_id/discussion_topics
GET /api/v1/groups/:group_id/discussion_topics
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:
If “overrides” is passed, the overrides for the assignment will be included
Allowed values: |
|
order_by | string |
Determines the order of the discussion topic list. Defaults to “position”.
Allowed values: |
|
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: |
|
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: |
|
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>'
Create a new discussion topic DiscussionTopicsController#create
POST /api/v1/courses/:course_id/discussion_topics
url:POST|/api/v1/courses/:course_id/discussion_topics
POST /api/v1/groups/:group_id/discussion_topics
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: |
|
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
url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id
PUT /api/v1/groups/:group_id/discussion_topics/:topic_id
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: |
|
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
url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id
DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id
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
url:POST|/api/v1/courses/:course_id/discussion_topics/reorder
POST /api/v1/groups/:group_id/discussion_topics/reorder
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
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
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
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
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
url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id
GET /api/v1/groups/:group_id/discussion_topics/:topic_id
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:
If “overrides” is passed, the overrides for the assignment will be included
Allowed values: |
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
url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/summaries
GET /api/v1/groups/:group_id/discussion_topics/:topic_id/summaries
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
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
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
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
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:
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
url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/view
GET /api/v1/groups/:group_id/discussion_topics/:topic_id/view
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
url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries
POST /api/v1/groups/:group_id/discussion_topics/:topic_id/entries
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
url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/duplicate
POST /api/v1/groups/:group_id/discussion_topics/:topic_id/duplicate
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
List topic entries DiscussionTopicsApiController#entries
GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entries
url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries
GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entries
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
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
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
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
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
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
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
url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/read
PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/read
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
url:PUT|/api/v1/courses/:course_id/discussion_topics/read_all
PUT /api/v1/groups/:group_id/discussion_topics/read_all
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
url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/read
DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/read
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
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
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
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
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
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
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
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
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
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
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
url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed
PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed
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
url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed
DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed
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
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 |
Update enrollment term TermsController#update
PUT /api/v1/accounts/:account_id/terms/:id
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 |
Delete enrollment term TermsController#destroy
DELETE /api/v1/accounts/:account_id/terms/:id
url:DELETE|/api/v1/accounts/:account_id/terms/:id
Delete the specified enrollment term.
Returns an EnrollmentTerm objectList enrollment terms TermsApiController#index
GET /api/v1/accounts/:account_id/terms
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: |
|
include[] | string |
Array of additional information to include.
Allowed values: |
|
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"
}
}
}
]
}
Retrieve enrollment term TermsApiController#show
GET /api/v1/accounts/:account_id/terms/:id
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
List enrollments EnrollmentsApiController#index
GET /api/v1/courses/:course_id/enrollments
url:GET|/api/v1/courses/:course_id/enrollments
GET /api/v1/sections/:section_id/enrollments
url:GET|/api/v1/sections/:section_id/enrollments
GET /api/v1/users/:user_id/enrollments
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):
Allowed values: |
|
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: |
|
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 |
Enrollment by ID EnrollmentsApiController#show
GET /api/v1/accounts/:account_id/enrollments/:id
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 |
Enroll a user EnrollmentsApiController#create
POST /api/v1/courses/:course_id/enrollments
url:POST|/api/v1/courses/:course_id/enrollments
POST /api/v1/sections/:section_id/enrollments
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: |
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: |
|
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.
|
|
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'
Conclude, deactivate, or delete an enrollment EnrollmentsApiController#destroy
DELETE /api/v1/courses/:course_id/enrollments/:id
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: |
Example Request:
curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id \
-X DELETE \
-F 'task=conclude'
Accept Course Invitation EnrollmentsApiController#accept
POST /api/v1/courses/:course_id/enrollments/:id/accept
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
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
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
Add last attended date EnrollmentsApiController#last_attended
PUT /api/v1/courses/:course_id/users/:user_id/last_attended
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)
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
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
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 |
moderate_user_content.
Allowed values: |
Get an ePortfolio EportfoliosApiController#show
GET /api/v1/eportfolios/:id
url:GET|/api/v1/eportfolios/:id
Get details for a single ePortfolio.
Returns an ePortfolio objectDelete an ePortfolio EportfoliosApiController#delete
DELETE /api/v1/eportfolios/:id
url:DELETE|/api/v1/eportfolios/:id
Mark an ePortfolio as deleted.
Returns an ePortfolio objectGet ePortfolio Pages EportfoliosApiController#pages
GET /api/v1/eportfolios/:eportfolio_id/pages
url:GET|/api/v1/eportfolios/:eportfolio_id/pages
Get details for the pages of an ePortfolio
Returns a list of ePortfolioPage objectsModerate an ePortfolio EportfoliosApiController#moderate
PUT /api/v1/eportfolios/:eportfolio_id/moderate
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: |
Moderate all ePortfolios for a User EportfoliosApiController#moderate_all
PUT /api/v1/users/:user_id/eportfolios
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: |
Restore a deleted ePortfolio EportfoliosApiController#restore
PUT /api/v1/eportfolios/:eportfolio_id/restore
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 objectList courses with their latest ePub export EpubExportsController#index
GET /api/v1/epub_exports
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 objectsCreate ePub Export EpubExportsController#create
POST /api/v1/courses/:course_id/epub_exports
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 objectShow ePub export EpubExportsController#show
GET /api/v1/courses/:course_id/epub_exports/:id
url:GET|/api/v1/courses/:course_id/epub_exports/:id
Get information about a single ePub export.
Returns an EpubExport objectCreate Error Report ErrorsController#create
POST /api/v1/error_reports
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
url:GET|/api/v1/courses/:course_id/external_tools
GET /api/v1/accounts/:account_id/external_tools
url:GET|/api/v1/accounts/:account_id/external_tools
GET /api/v1/groups/:group_id/external_tools
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
url:GET|/api/v1/courses/:course_id/external_tools/sessionless_launch
GET /api/v1/accounts/:account_id/external_tools/sessionless_launch
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: |
|
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
url:GET|/api/v1/courses/:course_id/external_tools/:external_tool_id
GET /api/v1/accounts/:account_id/external_tools/:external_tool_id
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
url:POST|/api/v1/courses/:course_id/external_tools
POST /api/v1/accounts/:account_id/external_tools
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: |
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: |
|
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: |
|
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: |
|
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: |
|
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
url:PUT|/api/v1/courses/:course_id/external_tools/:external_tool_id
PUT /api/v1/accounts/:account_id/external_tools/:external_tool_id
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
url:DELETE|/api/v1/courses/:course_id/external_tools/:external_tool_id
DELETE /api/v1/accounts/:account_id/external_tools/:external_tool_id
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
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
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
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
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
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, |
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
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
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>'
List favorite groups FavoritesController#list_favorite_groups
GET /api/v1/users/self/favorites/groups
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>'
Add course to favorites FavoritesController#add_favorite_course
POST /api/v1/users/self/favorites/courses/:id
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'
Add group to favorites FavoritesController#add_favorite_groups
POST /api/v1/users/self/favorites/groups/:id
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'
Remove course from favorites FavoritesController#remove_favorite_course
DELETE /api/v1/users/self/favorites/courses/:id
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>'
Remove group from favorites FavoritesController#remove_favorite_groups
DELETE /api/v1/users/self/favorites/groups/:id
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>'
Reset course favorites FavoritesController#reset_course_favorites
DELETE /api/v1/users/self/favorites/courses
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
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
url:GET|/api/v1/courses/:course_id/features
GET /api/v1/accounts/:account_id/features
url:GET|/api/v1/accounts/:account_id/features
GET /api/v1/users/:user_id/features
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>"
List enabled features FeatureFlagsController#enabled_features
GET /api/v1/courses/:course_id/features/enabled
url:GET|/api/v1/courses/:course_id/features/enabled
GET /api/v1/accounts/:account_id/features/enabled
url:GET|/api/v1/accounts/:account_id/features/enabled
GET /api/v1/users/:user_id/features/enabled
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
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
url:GET|/api/v1/courses/:course_id/features/flags/:feature
GET /api/v1/accounts/:account_id/features/flags/:feature
url:GET|/api/v1/accounts/:account_id/features/flags/:feature
GET /api/v1/users/:user_id/features/flags/:feature
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>"
Set feature flag FeatureFlagsController#update
PUT /api/v1/courses/:course_id/features/flags/:feature
url:PUT|/api/v1/courses/:course_id/features/flags/:feature
PUT /api/v1/accounts/:account_id/features/flags/:feature
url:PUT|/api/v1/accounts/:account_id/features/flags/:feature
PUT /api/v1/users/:user_id/features/flags/:feature
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 |
Allowed values: |
Example Request:
curl -X PUT 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
-H "Authorization: Bearer " \
-F "state=on"
Remove feature flag FeatureFlagsController#delete
DELETE /api/v1/courses/:course_id/features/flags/:feature
url:DELETE|/api/v1/courses/:course_id/features/flags/:feature
DELETE /api/v1/accounts/:account_id/features/flags/:feature
url:DELETE|/api/v1/accounts/:account_id/features/flags/:feature
DELETE /api/v1/users/:user_id/features/flags/:feature
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>"
Get quota information FilesController#api_quota
GET /api/v1/courses/:course_id/files/quota
url:GET|/api/v1/courses/:course_id/files/quota
GET /api/v1/groups/:group_id/files/quota
url:GET|/api/v1/groups/:group_id/files/quota
GET /api/v1/users/:user_id/files/quota
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
url:GET|/api/v1/courses/:course_id/files
GET /api/v1/users/:user_id/files
url:GET|/api/v1/users/:user_id/files
GET /api/v1/groups/:group_id/files
url:GET|/api/v1/groups/:group_id/files
GET /api/v1/folders/:id/files
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.
Allowed values: |
|
only[] | Array |
Array of information to restrict to. Overrides include[]
|
|
sort | string |
Sort results by this field. Defaults to ‘name’. Note that ‘sort=user` implies `include[]=user`.
Allowed values: |
|
order | string |
The sorting order. Defaults to ‘asc’.
Allowed values: |
Example Request:
curl 'https://<canvas>/api/v1/folders/<folder_id>/files?content_types[]=image&content_types[]=text/plain \
-H 'Authorization: Bearer <token>'
Get public inline preview url FilesController#public_url
GET /api/v1/files/:id/public_url
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
url:GET|/api/v1/files/:id
POST /api/v1/files/:id
url:POST|/api/v1/files/:id
GET /api/v1/courses/:course_id/files/:id
url:GET|/api/v1/courses/:course_id/files/:id
GET /api/v1/groups/:group_id/files/:id
url:GET|/api/v1/groups/:group_id/files/:id
GET /api/v1/users/:user_id/files/:id
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.
Allowed values: |
|
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>'
Translate file reference FilesController#file_ref
GET /api/v1/courses/:course_id/files/file_ref/:migration_id
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>'
Update file FilesController#api_update
PUT /api/v1/files/:id
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.
Allowed values: |
|
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>'
Delete file FilesController#destroy
DELETE /api/v1/files/:id
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>'
Get icon metadata FilesController#icon_metadata
GET /api/v1/files/:id/icon_metadata
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
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>'
List folders FoldersController#api_index
GET /api/v1/folders/:id/folders
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>'
List folders and files FoldersController#list_folders_and_files
GET /api/v1/folders/:id/all
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>'
List all folders FoldersController#list_all_folders
GET /api/v1/courses/:course_id/folders
url:GET|/api/v1/courses/:course_id/folders
GET /api/v1/users/:user_id/folders
url:GET|/api/v1/users/:user_id/folders
GET /api/v1/groups/:group_id/folders
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>'
Resolve path FoldersController#resolve_path
GET /api/v1/courses/:course_id/folders/by_path/*full_path
url:GET|/api/v1/courses/:course_id/folders/by_path/*full_path
GET /api/v1/courses/:course_id/folders/by_path
url:GET|/api/v1/courses/:course_id/folders/by_path
GET /api/v1/users/:user_id/folders/by_path/*full_path
url:GET|/api/v1/users/:user_id/folders/by_path/*full_path
GET /api/v1/users/:user_id/folders/by_path
url:GET|/api/v1/users/:user_id/folders/by_path
GET /api/v1/groups/:group_id/folders/by_path/*full_path
url:GET|/api/v1/groups/:group_id/folders/by_path/*full_path
GET /api/v1/groups/:group_id/folders/by_path
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>'
Get folder FoldersController#show
GET /api/v1/courses/:course_id/folders/:id
url:GET|/api/v1/courses/:course_id/folders/:id
GET /api/v1/users/:user_id/folders/:id
url:GET|/api/v1/users/:user_id/folders/:id
GET /api/v1/groups/:group_id/folders/:id
url:GET|/api/v1/groups/:group_id/folders/:id
GET /api/v1/folders/:id
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>'
Update folder FoldersController#update
PUT /api/v1/folders/:id
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>'
Create folder FoldersController#create
POST /api/v1/courses/:course_id/folders
url:POST|/api/v1/courses/:course_id/folders
POST /api/v1/users/:user_id/folders
url:POST|/api/v1/users/:user_id/folders
POST /api/v1/groups/:group_id/folders
url:POST|/api/v1/groups/:group_id/folders
POST /api/v1/folders/:folder_id/folders
url:POST|/api/v1/folders/:folder_id/folders
POST /api/v1/accounts/:account_id/folders
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>'
Delete folder FoldersController#api_destroy
DELETE /api/v1/folders/:id
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
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
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.
Allowed values: |
Example Request:
curl 'https://<canvas>/api/v1/folders/123/copy_file' \
-H 'Authorization: Bearer <token>'
-F 'source_file_id=456'
Copy a folder FoldersController#copy_folder
POST /api/v1/folders/:dest_folder_id/copy_folder
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'
Get uploaded media folder for user FoldersController#media_folder
GET /api/v1/courses/:course_id/folders/media
url:GET|/api/v1/courses/:course_id/folders/media
GET /api/v1/groups/:group_id/folders/media
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>'
Set usage rights UsageRightsController#set_usage_rights
PUT /api/v1/courses/:course_id/usage_rights
url:PUT|/api/v1/courses/:course_id/usage_rights
PUT /api/v1/groups/:group_id/usage_rights
url:PUT|/api/v1/groups/:group_id/usage_rights
PUT /api/v1/users/:user_id/usage_rights
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: |
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. |
Remove usage rights UsageRightsController#remove_usage_rights
DELETE /api/v1/courses/:course_id/usage_rights
url:DELETE|/api/v1/courses/:course_id/usage_rights
DELETE /api/v1/groups/:group_id/usage_rights
url:DELETE|/api/v1/groups/:group_id/usage_rights
DELETE /api/v1/users/:user_id/usage_rights
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
url:GET|/api/v1/courses/:course_id/content_licenses
GET /api/v1/groups/:group_id/content_licenses
url:GET|/api/v1/groups/:group_id/content_licenses
GET /api/v1/users/:user_id/content_licenses
url:GET|/api/v1/users/:user_id/content_licenses
A paginated list of licenses that can be applied
Returns a list of License objectsQuery by assignment GradeChangeAuditApiController#for_assignment
GET /api/v1/audit/grade_change/assignments/:assignment_id
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. |
Query by course GradeChangeAuditApiController#for_course
GET /api/v1/audit/grade_change/courses/:course_id
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. |
Query by student GradeChangeAuditApiController#for_student
GET /api/v1/audit/grade_change/students/:student_id
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. |
Query by grader GradeChangeAuditApiController#for_grader
GET /api/v1/audit/grade_change/graders/:grader_id
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. |
Advanced query GradeChangeAuditApiController#query
GET /api/v1/audit/grade_change
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. |
Days in gradebook history for this course GradebookHistoryApiController#days
GET /api/v1/courses/:course_id/gradebook_history/days
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 |
Details for a given date in gradebook history for this course GradebookHistoryApiController#day_details
GET /api/v1/courses/:course_id/gradebook_history/:date
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 |
Lists submissions GradebookHistoryApiController#submissions
GET /api/v1/courses/:course_id/gradebook_history/:date/graders/:grader_id/assignments/:assignment_id/submissions
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 |
List uncollated submission versions GradebookHistoryApiController#feed
GET /api/v1/courses/:course_id/gradebook_history/feed
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). |
List grading period sets GradingPeriodSetsController#index
GET /api/v1/accounts/:account_id/grading_period_sets
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
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
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
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
url:GET|/api/v1/accounts/:account_id/grading_periods
GET /api/v1/courses/:course_id/grading_periods
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
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
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
url:DELETE|/api/v1/courses/:course_id/grading_periods/:id
DELETE /api/v1/accounts/:account_id/grading_periods/:id
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
url:PATCH|/api/v1/courses/:course_id/grading_periods/batch_update
PATCH /api/v1/grading_period_sets/:set_id/grading_periods/batch_update
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
url:POST|/api/v1/accounts/:account_id/grading_standards
POST /api/v1/courses/:course_id/grading_standards
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}
]
}
List the grading standards available in a context. GradingStandardsApiController#context_index
GET /api/v1/courses/:course_id/grading_standards
url:GET|/api/v1/courses/:course_id/grading_standards
GET /api/v1/accounts/:account_id/grading_standards
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>'
Get a single grading standard in a context. GradingStandardsApiController#context_show
GET /api/v1/courses/:course_id/grading_standards/:grading_standard_id
url:GET|/api/v1/courses/:course_id/grading_standards/:grading_standard_id
GET /api/v1/accounts/:account_id/grading_standards/:grading_standard_id
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>'
List group categories for a context GroupCategoriesController#index
GET /api/v1/accounts/:account_id/group_categories
url:GET|/api/v1/accounts/:account_id/group_categories
GET /api/v1/courses/:course_id/group_categories
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:
|
Example Request:
curl https://<canvas>/api/v1/accounts/<account_id>/group_categories \
-H 'Authorization: Bearer <token>' \
-d 'collaboration_state=all'
Get a single group category GroupCategoriesController#show
GET /api/v1/group_categories/:group_category_id
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>'
Create a Group Category GroupCategoriesController#create
POST /api/v1/accounts/:account_id/group_categories
url:POST|/api/v1/accounts/:account_id/group_categories
POST /api/v1/courses/:course_id/group_categories
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:
Allowed values: |
|
auto_leader | string |
Assigns group leaders automatically when generating and allocating students to groups Valid values are:
Allowed values: |
|
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>'
Bulk manage groups in category GroupCategoriesController#bulk_manage_groups
POST /api/v1/group_categories/:group_category_id/bulk_manage_groups
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: {
} |
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}]
}
}'
Import category groups GroupCategoriesController#import
POST /api/v1/group_categories/:group_category_id/import
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:
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:
|
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"
}
Update a Group Category GroupCategoriesController#update
PUT /api/v1/group_categories/:group_category_id
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:
Allowed values: |
|
auto_leader | string |
Assigns group leaders automatically when generating and allocating students to groups Valid values are:
Allowed values: |
|
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>'
Delete a Group Category GroupCategoriesController#destroy
DELETE /api/v1/group_categories/:group_category_id
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
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>'
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
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
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>'
Assign unassigned members GroupCategoriesController#assign_unassigned_members
POST /api/v1/group_categories/:group_category_id/assign_unassigned_members
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
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: |
|
include[] | string |
Allowed values: |
Example Request:
curl https://<canvas>/api/v1/users/self/groups?context_type=Account \
-H 'Authorization: Bearer <token>'
List the groups available in a context. GroupsController#context_index
GET /api/v1/accounts/:account_id/groups
url:GET|/api/v1/accounts/:account_id/groups
GET /api/v1/courses/:course_id/groups
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 |
Allowed values: |
|
collaboration_state | string |
Filter groups by their collaboration state:
|
Example Request:
curl https://<canvas>/api/v1/courses/1/groups \
-H 'Authorization: Bearer <token>'
Get a single group GroupsController#show
GET /api/v1/groups/:group_id
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 |
Allowed values: |
Example Request:
curl https://<canvas>/api/v1/groups/<group_id> \
-H 'Authorization: Bearer <token>'