Create an access token TokensController#create

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:

Update an access token TokensController#update

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.

Request Parameters:

Delete an access token TokensController#destroy

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

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:

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

Get details about a specific account calendar.

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

Update a calendar AccountCalendarsApiController#update

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:

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

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.

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

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:

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

Returns the number of visible account calendars.

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

Search account domains

GET /api/v1/accounts/search

Returns a list of up to 5 matching account domains

Partial match on name / domain are supported

Request Parameters:

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

[
  {
    "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

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.

Request Parameters:

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

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

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

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

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

Create and return a new global notification for an account.

Request Parameters:

account_notification_roles: ["StudentEnrollment", "TeacherEnrollment"]

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'

{
  "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

Update global notification for an account.

Request Parameters:

account_notification_roles: ["StudentEnrollment", "TeacherEnrollment"]

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'

{
  "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

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

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

[
  {
    "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

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:

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

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

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

Returns the status of a report.

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

Deletes a generated report instance.

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

List accounts AccountsController#index

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:

Get accounts that admins can manage AccountsController#manageable_accounts

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.

Get accounts that users can create courses in AccountsController#course_creation_accounts

GET /api/v1/course_creation_accounts

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

List accounts for course admins AccountsController#course_accounts

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”

Get a single account AccountsController#show

GET /api/v1/accounts/:id

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

Settings AccountsController#show_settings

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.

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

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

List environment settings AccountsController#environment

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.

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

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

Permissions AccountsController#permissions

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:

curl https://<canvas>/api/v1/accounts/self/permissions \
  -H 'Authorization: Bearer <token>' \
  -d 'permissions[]=manage_account_memberships' \
  -d 'permissions[]=become_user'

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

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

Request Parameters:

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

Returns the terms of service for that account

Get help links AccountsController#help_links

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

Returns the help links for that account

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

GET /api/v1/manually_created_courses_account

List active courses in an account AccountsController#courses_api

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

Retrieve a paginated list of courses in this account.

Request Parameters:

Update an account AccountsController#update

PUT /api/v1/accounts/:id

Update an existing account.

Request Parameters:

Enhance password options

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

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.

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

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

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

Add a new sub-account to a given account.

Request Parameters:

Delete a sub-account SubAccountsController#destroy

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

Get account Lti::AccountLookupController#show

GET /api/lti/accounts/:account_id

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

Make an account admin AdminsController#create

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

Flag an existing user as an admin within the account.

Request Parameters:

Remove account admin AdminsController#destroy

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

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

Request Parameters:

List account admins AdminsController#index

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

A paginated list of the admins in the account

Request Parameters:

List my admin roles AdminsController#self_roles

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

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

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.

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

{
  "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

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

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.

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

{
  "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

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

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.

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

{
  "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

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

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.

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

{"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

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

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

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

Get course-level assignment data

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:

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

[
  {
    "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

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:

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

[
  {
    "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

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.

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

{
  "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

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.

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

[
  {
    "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

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.

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

{
  "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

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

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

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

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

Create a new external feed for the course or group.

Request Parameters:

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

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

Deletes the external feed.

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

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:

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

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

[{
  "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

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

Request Parameters:

List appointment groups AppointmentGroupsController#index

GET /api/v1/appointment_groups

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

Request Parameters:

Create an appointment group AppointmentGroupsController#create

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:

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

Returns information for a single appointment group

Request Parameters:

Update an appointment group AppointmentGroupsController#update

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:

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

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

Request Parameters:

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

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:

List student group participants AppointmentGroupsController#groups

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:

Get next appointment AppointmentGroupsController#next_appointment

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:

Set extensions for student assignment submissions AssignmentExtensionsController#create

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:

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

{
  "assignment_extensions": [AssignmentExtension]
}

List assignment groups AssignmentGroupsController#index

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:

Get an Assignment Group AssignmentGroupsApiController#show

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

Returns the assignment group with the given id.

Request Parameters:

Create an Assignment Group AssignmentGroupsApiController#create

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

Create a new assignment group for this course.

Request Parameters:

Edit an Assignment Group AssignmentGroupsApiController#update

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

Modify an existing Assignment Group.

Request Parameters:

Destroy an Assignment Group AssignmentGroupsApiController#destroy

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

Deletes the assignment group with the given id.

Request Parameters:

Delete an assignment AssignmentsController#destroy

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

Delete the given assignment.

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

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:

List assignments for user AssignmentsApiController#user_index

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

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

Request Parameters:

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

Returns student ids and names for the group.

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

Returns the assignment with the given id.

Request Parameters:

Create an assignment AssignmentsApiController#create

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

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

Request Parameters:

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

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

allowed_extensions: ["docx","ppt"]

Edit an assignment AssignmentsApiController#update

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

Modify an existing assignment.

Request Parameters:

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

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

allowed_extensions: ["docx","ppt"]

Bulk update assignment dates AssignmentsApiController#bulk_update

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.

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

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

Get a single assignment override AssignmentOverridesController#show

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

Returns details of the the override with the given id.

Redirect to the assignment override for a group AssignmentOverridesController#group_alias

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

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

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:

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

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:

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

Deletes an override and returns its former details.

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

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:

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

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:

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

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:

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

Returns a paginated list of authentication providers

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

Add authentication provider AuthenticationProvidersController#create

POST /api/v1/accounts/:account_id/authentication_providers

Add external authentication provider(s) for the account. Services may be Apple, CAS, Facebook, GitHub, Google, LDAP, LinkedIn, Microsoft, OpenID Connect, SAML, or X.com.

Each authentication provider is specified as a set of parameters as described below. A provider specification must include an ‘auth_type’ parameter with a value of ‘apple’, ‘canvas’, ‘cas’, ‘clever’, ‘facebook’, ‘github’, ‘google’, ‘ldap’, ‘linkedin’, ‘microsoft’, ‘openid_connect’, ‘saml’, or ‘twitter’. The other recognized parameters depend on this auth_type; unrecognized parameters are discarded. Provider specifications not specifying a valid auth_type are ignored.

You can set the ‘position’ for any provider. The config in the 1st position is considered the default. You can set ‘jit_provisioning’ for any provider besides Canvas. You can set ‘mfa_required’ for any provider.

For Apple, the additional recognized parameters are:

• client_id [Required]

  The developer’s client identifier, as provided by WWDR. Not available if configured globally for Canvas.

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘sub’ (the default), or ‘email’

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘firstName’, ‘lastName’, and ‘sub’.

For Canvas, the additional recognized parameter is:

• self_registration

  ‘all’, ‘none’, or ‘observer’ - who is allowed to register as a new user

For CAS, the additional recognized parameters are:

• auth_base

  The CAS server’s URL.

• log_in_url [Optional]

  An alternate SSO URL for logging into CAS. You probably should not set this.

For Clever, the additional recognized parameters are:

• client_id [Required]

  The Clever application’s Client ID. Not available if configured globally for Canvas.

• client_secret [Required]

  The Clever application’s Client Secret. Not available if configured globally for Canvas.

• district_id [Optional]

  A district’s Clever ID. Leave this blank to let Clever handle the details with its District Picker. This is required for Clever Instant Login to work in a multi-tenant environment.

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), ‘sis_id’, ‘email’, ‘student_number’, or ‘teacher_number’. Note that some fields may not be populated for all users at Clever.

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘id’, ‘sis_id’, ‘email’, ‘student_number’, and ‘teacher_number’.

For Facebook, the additional recognized parameters are:

• app_id [Required]

  The Facebook App ID. Not available if configured globally for Canvas.

• app_secret [Required]

  The Facebook App Secret. Not available if configured globally for Canvas.

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), or ‘email’

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘first_name’, ‘id’, ‘last_name’, ‘locale’, and ‘name’.

For GitHub, the additional recognized parameters are:

• domain [Optional]

  The domain of a GitHub Enterprise installation. I.e. github.mycompany.com. If not set, it will default to the public github.com.

• client_id [Required]

  The GitHub application’s Client ID. Not available if configured globally for Canvas.

• client_secret [Required]

  The GitHub application’s Client Secret. Not available if configured globally for Canvas.

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), or ‘login’

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘id’, ‘login’, and ‘name’.

For Google, the additional recognized parameters are:

• client_id [Required]

  The Google application’s Client ID. Not available if configured globally for Canvas.

• client_secret [Required]

  The Google application’s Client Secret. Not available if configured globally for Canvas.

• hosted_domain [Optional]

  A Google Apps domain to restrict logins to. See developers.google.com/identity/protocols/OpenIDConnect?hl=en#hd-param

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘sub’ (the default), or ‘email’

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘family_name’, ‘given_name’, ‘locale’, ‘name’, and ‘sub’.

For LDAP, the additional recognized parameters are:

• auth_host

  The LDAP server’s URL.

• auth_port [Optional, Integer]

  The LDAP server’s TCP port. (default: 389)

• auth_over_tls [Optional]

  Whether to use TLS. Can be ‘simple_tls’, or ‘start_tls’. For backwards compatibility, booleans are also accepted, with true meaning simple_tls. If not provided, it will default to start_tls.

• auth_base [Optional]

  A default treebase parameter for searches performed against the LDAP server.

• auth_filter

  LDAP search filter. Use {{login}} as a placeholder for the username supplied by the user. For example: “(sAMAccountName={{login}})”.

• identifier_format [Optional]

  The LDAP attribute to use to look up the Canvas login. Omit to use the username supplied by the user.

• auth_username

  Username

• auth_password

  Password

For LinkedIn, the additional recognized parameters are:

• client_id [Required]

  The LinkedIn application’s Client ID. Not available if configured globally for Canvas.

• client_secret [Required]

  The LinkedIn application’s Client Secret. Not available if configured globally for Canvas.

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), or ‘emailAddress’

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘emailAddress’, ‘firstName’, ‘id’, ‘formattedName’, and ‘lastName’.

For Microsoft, the additional recognized parameters are:

• application_id [Required]

  The application’s ID.

• application_secret [Required]

  The application’s Client Secret (Password)

• tenant [Optional]

  See azure.microsoft.com/en-us/documentation/articles/active-directory-v2-protocols/ Valid values are ‘common’, ‘organizations’, ‘consumers’, or an Azure Active Directory Tenant (as either a UUID or domain, such as contoso.onmicrosoft.com). Defaults to ‘common’

• login_attribute [Optional]

  See azure.microsoft.com/en-us/documentation/articles/active-directory-v2-tokens/#idtokens Valid values are ‘sub’, ‘email’, ‘oid’, or ‘preferred_username’. Note that email may not always be populated in the user’s profile at Microsoft. Oid will not be populated for personal Microsoft accounts. Defaults to ‘sub’

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘name’, ‘preferred_username’, ‘oid’, and ‘sub’.

For OpenID Connect, the additional recognized parameters are:

• client_id [Required]

  The application’s Client ID.

• client_secret [Required]

  The application’s Client Secret.

• authorize_url [Required]

  The URL for getting starting the OAuth 2.0 web flow

• token_url [Required]

  The URL for exchanging the OAuth 2.0 authorization code for an Access Token and ID Token

• scope [Optional]

  Space separated additional scopes to request for the token. Note that you need not specify the ‘openid’ scope, or any scopes that can be automatically inferred by the rules defined at openid.net/specs/openid-connect-core-1_0.html#ScopeClaims

• end_session_endpoint [Optional]

  URL to send the end user to after logging out of Canvas. See openid.net/specs/openid-connect-session-1_0.html#RPLogout

• userinfo_endpoint [Optional]

  URL to request additional claims from. If the initial ID Token received from the provider cannot be used to satisfy the login_attribute and all federated_attributes, this endpoint will be queried for additional information.

• login_attribute [Optional]

  The attribute of the ID Token to look up the user’s login in Canvas. Defaults to ‘sub’.

• federated_attributes [Optional]

  See FederatedAttributesConfig. Any value is allowed for the provider attribute names, but standard claims are listed at openid.net/specs/openid-connect-core-1_0.html#StandardClaims

For SAML, the additional recognized parameters are:

• metadata [Optional]

  An XML document to parse as SAML metadata, and automatically populate idp_entity_id, log_in_url, log_out_url, certificate_fingerprint, and identifier_format

• metadata_uri [Optional]

  A URI to download the SAML metadata from, and automatically populate idp_entity_id, log_in_url, log_out_url, certificate_fingerprint, and identifier_format. This URI will also be saved, and the metadata periodically refreshed, automatically. If the metadata contains multiple entities, also supply idp_entity_id to distinguish which one you want (otherwise the only entity in the metadata will be inferred). If you provide the URI ‘urn:mace:incommon’ or ‘ukfederation.org.uk’, the InCommon or UK Access Management Federation metadata aggregate, respectively, will be used instead, and additional validation checks will happen (including validating that the metadata has been properly signed with the appropriate key).

• idp_entity_id

  The SAML IdP’s entity ID

• log_in_url

  The SAML service’s SSO target URL

• log_out_url [Optional]

  The SAML service’s SLO target URL

• certificate_fingerprint

  The SAML service’s certificate fingerprint.

• identifier_format

  The SAML service’s identifier format. Must be one of:

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  • urn:oasis:names:tc:SAML:2.0:nameid-format:entity

  • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient

  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

  • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

  • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

• requested_authn_context [Optional]

  The SAML AuthnContext

• sig_alg [Optional]

  If set, AuthnRequest, LogoutRequest, and LogoutResponse messages are signed with the corresponding algorithm. Supported algorithms are:

  • http://www.w3.org/2000/09/xmldsig#rsa-sha1

  • http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

  RSA-SHA1 and RSA-SHA256 are acceptable aliases.

• federated_attributes [Optional]

  See FederatedAttributesConfig. Any value is allowed for the provider attribute names.

For X.com, the additional recognized parameters are:

• consumer_key [Required]

  The X.com Consumer Key. Not available if configured globally for Canvas.

• consumer_secret [Required]

  The X.com Consumer Secret. Not available if configured globally for Canvas.

• login_attribute [Optional]

  The attribute to use to look up the user’s login in Canvas. Either ‘user_id’ (the default), or ‘screen_name’

• parent_registration [Optional] - DEPRECATED 2017-11-03

  Accepts a boolean value, true designates the authentication service for use on parent registrations. Only one service can be selected at a time so if set to true all others will be set to false

• federated_attributes [Optional]

  See FederatedAttributesConfig. Valid provider attributes are ‘name’, ‘screen_name’, ‘time_zone’, and ‘user_id’.

# Create LDAP config
curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers' \
     -F 'auth_type=ldap' \
     -F 'auth_host=ldap.mydomain.edu' \
     -F 'auth_filter=(sAMAccountName={{login}})' \
     -F 'auth_username=username' \
     -F 'auth_password=bestpasswordever' \
     -F 'position=1' \
     -H 'Authorization: Bearer <token>'

# Create SAML config
curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers' \
     -F 'auth_type=saml' \
     -F 'idp_entity_id=<idp_entity_id>' \
     -F 'log_in_url=<login_url>' \
     -F 'log_out_url=<logout_url>' \
     -F 'certificate_fingerprint=<fingerprint>' \
     -H 'Authorization: Bearer <token>'

# Create CAS config
curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers' \
     -F 'auth_type=cas' \
     -F 'auth_base=cas.mydomain.edu' \
     -F 'log_in_url=<login_url>' \
     -H 'Authorization: Bearer <token>'

Update authentication provider AuthenticationProvidersController#update

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.

# update SAML config
curl -XPUT '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>'

Get authentication provider AuthenticationProvidersController#show

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

Get the specified authentication provider

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

Delete authentication provider AuthenticationProvidersController#destroy

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

Delete the config

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

show account auth settings AuthenticationProvidersController#show_sso_settings

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”

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

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”

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

List authentication events for a given login.

Request Parameters:

Query by account. AuthenticationAuditApiController#for_account

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

List authentication events for a given account.

Request Parameters:

Query by user. AuthenticationAuditApiController#for_user

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

List authentication events for a given user.

Request Parameters:

List blackout dates BlackoutDatesController#index

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

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

Returns the list of blackout dates for the current context.

Get a single blackout date BlackoutDatesController#show

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

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

Returns the blackout date with the given id.

New Blackout Date BlackoutDatesController#new

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

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

Initialize an unsaved Blackout Date for the given context.

Create Blackout Date BlackoutDatesController#create

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

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

Create a blackout date for the given context.

Request Parameters:

Update Blackout Date BlackoutDatesController#update

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

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

Update a blackout date for the given context.

Request Parameters:

Delete Blackout Date BlackoutDatesController#destroy

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

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

Delete a blackout date for the given context.

Update a list of Blackout Dates BlackoutDatesController#bulk_update

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

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

Request Parameters:

Get blueprint information MasterCourses::MasterTemplatesController#show

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

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

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

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

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:

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

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

Request Parameters:

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

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

Request Parameters:

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

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

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.

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

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

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

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.

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

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

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

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.

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

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

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

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

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

Returns the paginated list of bookmarks.

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

Create bookmark Bookmarks::BookmarksController#create

POST /api/v1/users/self/bookmarks

Creates a bookmark.

Request Parameters:

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

Returns the details for a bookmark.

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

Updates a bookmark

Request Parameters:

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

Deletes a bookmark

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

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.

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

List calendar events CalendarEventsApiController#index

GET /api/v1/calendar_events

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

Request Parameters:

List calendar events for a user CalendarEventsApiController#user_index

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:

Create a calendar event CalendarEventsApiController#create

POST /api/v1/calendar_events

Create and return a new calendar event

Request Parameters:

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

Reserve a time slot CalendarEventsApiController#reserve

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

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

Reserves a particular time slot and return the new reservation

Request Parameters:

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

Update and return a calendar event

Request Parameters:

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

Delete an event from the calendar and return the deleted event

Request Parameters:

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

Creates and updates the enabled_account_calendars and mark_feature_as_seen user preferences

Request Parameters:

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

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:

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

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

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:

List collaborations CollaborationsController#api_index

GET /api/v1/courses/:course_id/collaborations

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/

List members of a collaboration. CollaborationsController#members

GET /api/v1/collaborations/:id/members

A paginated list of the collaborators of a given collaboration

Request Parameters:

curl https://<canvas>/api/v1/courses/1/collaborations/1/members

List potential members CollaborationsController#potential_collaborators

GET /api/v1/courses/:course_id/potential_collaborators

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.

List of CommMessages for a user CommMessagesApiController#index

GET /api/v1/comm_messages

Retrieve a paginated list of messages sent to a user.

Request Parameters:

List user communication channels CommunicationChannelsController#index

GET /api/v1/users/:user_id/communication_channels

Returns a paginated list of communication channels for the specified user, sorted by position.

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

Creates a new communication channel for the specified user.

Request Parameters:

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

DELETE /api/v1/users/:user_id/communication_channels/:type/:address

Delete an existing communication channel.

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

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

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”

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

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:

curl 'https://<canvas>/api/v1/conferences' \
    -H "Authorization: Bearer <token>"

List content exports ContentExportsApiController#index

GET /api/v1/courses/:course_id/content_exports

GET /api/v1/groups/:group_id/content_exports

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.

Show content export ContentExportsApiController#show

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

GET /api/v1/groups/:group_id/content_exports/:id

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

Get information about a single content export.

Export content ContentExportsApiController#create

POST /api/v1/courses/:course_id/content_exports

POST /api/v1/groups/:group_id/content_exports

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:

List migration issues MigrationIssuesController#index

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

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

Returns paginated migration issues

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

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

GET /api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues/:id

Returns data on an individual migration issue

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

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

PUT /api/v1/users/:user_id/content_migrations/:content_migration_id/migration_issues/:id

Update the workflow_state of a migration issue

Request Parameters:

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

GET /api/v1/courses/:course_id/content_migrations

GET /api/v1/groups/:group_id/content_migrations

GET /api/v1/users/:user_id/content_migrations

Returns paginated content migrations

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

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

GET /api/v1/groups/:group_id/content_migrations/:id

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

Returns data on an individual content migration

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

POST /api/v1/courses/:course_id/content_migrations

POST /api/v1/groups/:group_id/content_migrations

POST /api/v1/users/:user_id/content_migrations

Create a content migration. If the migration requires a file to be uploaded the actual processing of the file will start once the file upload process is completed. File uploading works as described in the File Upload Documentation except that the values are set on a pre_attachment sub-hash.

For migrations that don’t require a file to be uploaded, like course copy, the processing will begin as soon as the migration is created.

You can use the Progress API to track the progress of the migration. The migration’s progress is linked to with the progress_url value.

The two general workflows are:

If no file upload is needed:

1. POST to create

2. Use the Progress specified in progress_url to monitor progress

For file uploading:

1. POST to create with file info in pre_attachment

2. Do file upload processing using the data in the pre_attachment data

3. GET the ContentMigration

4. Use the Progress specified in progress_url to monitor progress

(required if doing .zip file upload)

Request Parameters:

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

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

PUT /api/v1/groups/:group_id/content_migrations/:id

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.

List Migration Systems ContentMigrationsController#available_migrators

GET /api/v1/accounts/:account_id/content_migrations/migrators

GET /api/v1/courses/:course_id/content_migrations/migrators

GET /api/v1/groups/:group_id/content_migrations/migrators

GET /api/v1/users/:user_id/content_migrations/migrators

Lists the currently available migration types. These values may change.

List items for selective import ContentMigrationsController#content_list

GET /api/v1/accounts/:account_id/content_migrations/:id/selective_data

GET /api/v1/courses/:course_id/content_migrations/:id/selective_data

GET /api/v1/groups/:group_id/content_migrations/:id/selective_data

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:

Get asset id mapping ContentMigrationsController#asset_id_mapping

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.

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<id>/asset_id_mapping \
    -H 'Authorization: Bearer <token>'

{
  "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

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

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:

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

Can only be set if CSP is explicitly enabled or disabled on this account (i.e. “inherited” is false).

Request Parameters:

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

Adds an allowed domain for the current account. Note: this will not take effect unless CSP is explicitly enabled on this account.

Request Parameters:

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

Adds multiple allowed domains for the current account. Note: this will not take effect unless CSP is explicitly enabled on this account.

Request Parameters:

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

Removes an allowed domain from the current account.

Request Parameters:

Create a content share ContentSharesController#create

POST /api/v1/users/:user_id/content_shares

Share content directly between two or more users

Request Parameters:

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

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.

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

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.

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

Return information about a single content share. You may use self as the user_id to retrieve your own content share.

curl 'https://<canvas>/api/v1/users/self/content_shares/123'

Remove content share ContentSharesController#destroy

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.

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

Send a previously created content share to additional users

Request Parameters:

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

Mark a content share read or unread

Request Parameters:

curl -X PUT 'https://<canvas>/api/v1/users/self/content_shares/123?read_state=read'

List conversations ConversationsController#index

GET /api/v1/conversations

Returns the paginated list of conversations for the current user, most recent ones first.

Request Parameters:

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.

[
  {
    "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

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:

Get running batches ConversationsController#batches

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

[
  {
    "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

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:

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.

{
  "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

Updates attributes for a single conversation.

Request Parameters: