Community

All Resources Reference

Show an access token

TokensController#show

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

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

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

Create an access token

TokensController#create

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

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

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

Request Parameters:

Parameter
Type
Description

token[purpose]

Required string

The purpose of the token.

token[expires_at]

DateTime

The time at which the token will expire.

token[scopes][]

Array

The scopes to associate with the token.

Update an access token

TokensController#update

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

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

Update an existing access token.

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

Request Parameters:

Parameter
Type
Description

token[purpose]

string

The purpose of the token.

token[expires_at]

DateTime

The time at which the token will expire.

token[scopes][]

Array

The scopes to associate with the token.

token[regenerate]

boolean

Regenerate the actual token.

Delete an access token

TokensController#destroy

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

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

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

List available account calendars

AccountCalendarsApiController#index

GET /api/v1/account_calendars

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

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

Request Parameters:

Parameter
Type
Description

search_term

string

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

Example Request:

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

Returns a list of AccountCalendar objects.

Get a single account calendar

AccountCalendarsApiController#show

GET /api/v1/account_calendars/:account_id

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

Get details about a specific account calendar.

Example Request:

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

Returns an AccountCalendar object.

Update a calendar

AccountCalendarsApiController#update

PUT /api/v1/account_calendars/:account_id

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

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

Request Parameters:

Parameter
Type
Description

visible

boolean

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

auto_subscribe

boolean

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

Example Request:

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

Returns an AccountCalendar object.

Update several calendars

AccountCalendarsApiController#bulk_update

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

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

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

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

Returns the count of updated accounts.

Example Request:

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

List all account calendars

AccountCalendarsApiController#all_calendars

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

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

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

Request Parameters:

Parameter
Type
Description

search_term

string

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

filter

string

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

Allowed values: visible, hidden

Example Request:

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

Returns a list of AccountCalendar objects.

Count of all visible account calendars

AccountCalendarsApiController#visible_calendars_count

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

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

Returns the number of visible account calendars.

Example Request:

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

Search account domains

GET /api/v1/accounts/search

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

Returns a list of up to 5 matching account domains

Partial match on name / domain are supported

Request Parameters:

Parameter
Type
Description

name

string

campus name

domain

string

no description

latitude

number

no description

longitude

number

no description

Example Request:

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

Example Response:

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

Index of active global notification for the user

AccountNotificationsController#user_index

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

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

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

Request Parameters:

Parameter
Type
Description

include_past

boolean

Include past and dismissed global announcements.

include_all

boolean

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

Example Request:

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

Returns a list of AccountNotification objects.

Show a global notification

AccountNotificationsController#show

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

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

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

Example Request:

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

Returns an AccountNotification object.

Close notification for user

AccountNotificationsController#user_close_notification

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

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

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

Example Request:

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

Returns an AccountNotification object.

Create a global notification

AccountNotificationsController#create

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

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

Create and return a new global notification for an account.

Request Parameters:

Parameter
Type
Description

account_notification[subject]

Required string

The subject of the notification.

account_notification[message]

Required string

The message body of the notification.

account_notification[start_at]

Required DateTime

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

account_notification[end_at]

Required DateTime

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

account_notification[icon]

string

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

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

account_notification_roles[]

string

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

account_notification_roles: ["StudentEnrollment", "TeacherEnrollment"]

Example Request:

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

Example Response:

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

Update a global notification

AccountNotificationsController#update

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

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

Update global notification for an account.

Request Parameters:

Parameter
Type
Description

account_notification[subject]

string

The subject of the notification.

account_notification[message]

string

The message body of the notification.

account_notification[start_at]

DateTime

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

account_notification[end_at]

DateTime

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

account_notification[icon]

string

The icon to display with the notification.

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

account_notification_roles[]

string

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

account_notification_roles: ["StudentEnrollment", "TeacherEnrollment"]

Example Request:

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

Example Response:

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

List Available Reports

AccountReportsController#available_reports

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

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

Returns a paginated list of reports for the current context.

API response field:

  • name

The name of the report.

  • parameters

The parameters will vary for each report

Example Request:

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

Example Response:

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

Start a Report

AccountReportsController#create

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

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

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

Request Parameters:

Parameter
Type
Description

parameters

string

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

parameters[skip_message]

boolean

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

parameters[course_id]

integer

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

parameters[users]

boolean

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

Example Request:

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

Returns a Report object.

Index of Reports

AccountReportsController#index

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

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

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

Example Request:

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

Returns a list of Report objects.

Status of a Report

AccountReportsController#show

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

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

Returns the status of a report.

Example Request:

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

Returns a Report object.

Delete a Report

AccountReportsController#destroy

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

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

Deletes a generated report instance.

Example Request:

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

Returns a Report object.

Abort a Report

AccountReportsController#abort

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

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

Abort a report in progress

Example Request:

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

Returns a Report object.

List accounts

AccountsController#index

GET /api/v1/accounts

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

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

Request Parameters:

Parameter
Type
Description

include[]

string

Array of additional information to include.

  • “lti_guid”

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

  • “registration_settings”

    returns info about the privacy policy and terms of use

  • “services”

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

  • “course_count”

    returns the number of courses directly under each account

  • “sub_account_count”

    returns the number of sub-accounts directly under each account

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

Returns a list of Account objects.

Get accounts that admins can manage

AccountsController#manageable_accounts

GET /api/v1/manageable_accounts

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

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

Returns a list of Account objects.

Get accounts that users can create courses in

AccountsController#course_creation_accounts

GET /api/v1/course_creation_accounts

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

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

Returns a list of Account objects.

List accounts for course admins

AccountsController#course_accounts

GET /api/v1/course_accounts

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

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

Returns a list of Account objects.

Get a single account

AccountsController#show

GET /api/v1/accounts/:id

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

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

Returns an Account object.

Settings

AccountsController#show_settings

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

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

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

Example Request:

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

Example Response:

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

List environment settings

AccountsController#environment

GET /api/v1/settings/environment

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

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

Example Request:

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

Example Response:

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

Permissions

AccountsController#permissions

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

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

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

See also the Course and Group counterparts.

Request Parameters:

Parameter
Type
Description

permissions[]

string

List of permissions to check against the authenticated user. Permission names are documented in the Create a role endpoint.

Example Request:

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

Example Response:

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

Get the sub-accounts of an account

AccountsController#sub_accounts

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

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

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

Request Parameters:

Parameter
Type
Description

recursive

boolean

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

include[]

string

Array of additional information to include.

  • “course_count”

    returns the number of courses directly under each account

  • “sub_account_count”

    returns the number of sub-accounts directly under each account

Allowed values: course_count, sub_account_count

Example Request:

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

Returns a list of Account objects.

Get the Terms of Service

AccountsController#terms_of_service

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

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

Returns the terms of service for that account

Returns a TermsOfService object.

Get help links

AccountsController#help_links

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

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

Returns the help links for that account

Returns a HelpLinks object.

Get the manually-created courses sub-account for the domain root account

AccountsController#manually_created_courses_account

GET /api/v1/manually_created_courses_account

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

List active courses in an account

AccountsController#courses_api

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

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

Retrieve a paginated list of courses in this account.

Request Parameters:

Parameter
Type
Description

with_enrollments

boolean

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

enrollment_type[]

string

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

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

published

boolean

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

completed

boolean

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

blueprint

boolean

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

blueprint_associated

boolean

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

public

boolean

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

by_teachers[]

integer

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

by_subaccounts[]

integer

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

hide_enrollmentless_courses

boolean

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

state[]

string

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

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

enrollment_term_id

integer

If set, only includes courses from the specified term.

search_term

string

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

include[]

string

  • All explanations can be seen in the Course API index documentation

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

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

sort

string

The column to sort results by.

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

order

string

The order to sort the given column by.

Allowed values: asc, desc

search_by

string

The fi