All API Resources

List Authorization Configs AccountAuthorizationConfigsController#index

GET /api/v1/accounts/:account_id/account_authorization_configs

Returns the list of authorization configs

Example Request:

curl 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs' \ 
     -H 'Authorization: Bearer <token>'
Returns a list of AccountAuthorizationConfigs

Create Authorization Config AccountAuthorizationConfigsController#create

POST /api/v1/accounts/:account_id/account_authorization_configs

Add external account authentication service(s) for the account. Services may be CAS, SAML, or LDAP.

Each authentication service is specified as a set of parameters as described below. A service specification must include an 'auth_type' parameter with a value of 'cas', 'saml', or 'ldap'. The other recognized parameters depend on this auth_type; unrecognized parameters are discarded. Service specifications not specifying a valid auth_type are ignored.

Any service specification may include an optional 'login_handle_name' parameter. This parameter specifies the label used for unique login identifiers; for example: 'Login', 'Username', 'Student ID', etc. The default is 'Email'.

You can set the 'position' for any configuration. The config in the 1st position is considered the default.

For CAS authentication services, 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 SAML authentication services, the additional recognized parameters are:

  • idp_entity_id

    The SAML IdP's entity ID - This is used to look up the correct SAML IdP if multiple are configured

  • log_in_url

    The SAML service's SSO target URL

  • log_out_url

    The SAML service's SLO target URL

  • certificate_fingerprint

    The SAML service's certificate fingerprint.

  • change_password_url [Optional]

    Forgot Password URL. Leave blank for default Canvas behavior.

  • 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

    The SAML AuthnContext

For LDAP authentication services, 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

  • change_password_url [Optional]

    Forgot Password URL. Leave blank for default Canvas behavior.

  • account_authorization_config (deprecated) The nth service specification as described above. For instance, the auth_type of the first service is given by the account_authorization_config[auth_type] parameter. There must be either a single CAS or SAML specification, or one or more LDAP specifications. Additional services after an initial CAS or SAML service are ignored; additional non-LDAP services after an initial LDAP service are ignored.

Deprecated Examples:

This endpoint still supports a deprecated version of setting the authorization configs. If you send data in this format it is considered a snapshot of how the configs should be setup and will clear any configs not sent.

Simple CAS server integration.

[0][auth_type]=cas&
[0][auth_base]=cas.mydomain.edu

Single SAML server integration.

account_authorization_config[0][idp_entity_id]=http://idp.myschool.com/sso/saml2
account_authorization_config[0][log_in_url]=saml-sso.mydomain.com&
account_authorization_config[0][log_out_url]=saml-slo.mydomain.com&
account_authorization_config[0][certificate_fingerprint]=1234567890ABCDEF&
account_authorization_config[0][identifier_format]=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Two SAML server integration with discovery url.

discovery_url=http://www.myschool.com/sso/identity_provider_selection
account_authorization_config[0][idp_entity_id]=http://idp.myschool.com/sso/saml2&
account_authorization_config[0][log_in_url]=saml-sso.mydomain.com&
account_authorization_config[0][log_out_url]=saml-slo.mydomain.com&
account_authorization_config[0][certificate_fingerprint]=1234567890ABCDEF&
account_authorization_config[0][identifier_format]=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress&
account_authorization_config[1][idp_entity_id]=http://idp.otherschool.com/sso/saml2&
account_authorization_config[1][log_in_url]=saml-sso.otherdomain.com&
account_authorization_config[1][log_out_url]=saml-slo.otherdomain.com&
account_authorization_config[1][certificate_fingerprint]=ABCDEFG12345678789&
account_authorization_config[1][identifier_format]=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Single LDAP server integration.

account_authorization_config[0][auth_type]=ldap&
account_authorization_config[0][auth_host]=ldap.mydomain.edu&
account_authorization_config[0][auth_filter]=(sAMAccountName={{login}})&
account_authorization_config[0][auth_username]=username&
account_authorization_config[0][auth_password]=password

Multiple LDAP server integration.

account_authorization_config[0][auth_type]=ldap&
account_authorization_config[0][auth_host]=faculty-ldap.mydomain.edu&
account_authorization_config[0][auth_filter]=(sAMAccountName={{login}})&
account_authorization_config[0][auth_username]=username&
account_authorization_config[0][auth_password]=password&
account_authorization_config[1][auth_type]=ldap&
account_authorization_config[1][auth_host]=student-ldap.mydomain.edu&
account_authorization_config[1][auth_filter]=(sAMAccountName={{login}})&
account_authorization_config[1][auth_username]=username&
account_authorization_config[1][auth_password]=password

Example Request:

# Create LDAP config
curl 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs' \ 
     -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/account/<account_id>/account_authorization_configs' \ 
     -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/account/<account_id>/account_authorization_configs' \ 
     -F 'auth_type=cas' \ 
     -F 'auth_base=cas.mydomain.edu' \ 
     -F 'log_in_url=<login_url>' \ 
     -H 'Authorization: Bearer <token>'
Returns a AccountAuthorizationConfig

Update Authorization Config AccountAuthorizationConfigsController#update

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

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

Example Request:

# update SAML config
curl -XPUT 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs/<id>' \ 
     -F 'idp_entity_id=<new_idp_entity_id>' \ 
     -F 'log_in_url=<new_url>' \ 
     -H 'Authorization: Bearer <token>'
Returns a AccountAuthorizationConfig

Get Authorization Config AccountAuthorizationConfigsController#show

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

Get the specified authorization config

Example Request:

curl 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs/<id>' \ 
     -H 'Authorization: Bearer <token>'
Returns a AccountAuthorizationConfig

Delete Authorization Config AccountAuthorizationConfigsController#destroy

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

Delete the config

Example Request:

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

GET discovery url AccountAuthorizationConfigsController#show_discovery_url

GET /api/v1/accounts/:account_id/account_authorization_configs/discovery_url

Get the discovery url

Example Request:

curl 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs/discovery_url' \ 
     -H 'Authorization: Bearer <token>'
Returns a DiscoveryUrl

Set discovery url AccountAuthorizationConfigsController#update_discovery_url

PUT /api/v1/accounts/:account_id/account_authorization_configs/discovery_url

If you have multiple IdPs configured, you can set a `discovery_url`. If that is set, canvas will forward all users to that URL when they need to be authenticated. That page will need to then help the user figure out where they need to go to log in.

If no discovery url is configured, the 1st auth config will be used to attempt to authenticate the user.

Example Request:

curl -XPUT 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs/discovery_url' \ 
     -F 'discovery_url=<new_url>' \ 
     -H 'Authorization: Bearer <token>'
Returns a DiscoveryUrl

Delete discovery url AccountAuthorizationConfigsController#destroy_discovery_url

DELETE /api/v1/accounts/:account_id/account_authorization_configs/discovery_url

Clear discovery url

Example Request:

curl -XDELETE 'https://<canvas>/api/v1/account/<account_id>/account_authorization_configs/discovery_url' \ 
     -H 'Authorization: Bearer <token>'

List Available Reports AccountReportsController#available_reports

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

Returns the 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

Generates a report instance for the account.

Request Parameters:

  • [parameters]

    The parameters will vary for each report

Returns a Report

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.

Example Request:

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

Status of a Report AccountReportsController#show

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

Returns the status of a report.

Request Parameters:

  • report_id
    Integer

    The report id.

Example Request:

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

Delete a Report AccountReportsController#destroy

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

List accounts AccountsController#index

GET /api/v1/accounts

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

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.

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:

  • recursive
    Optional, 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.

Example Request:

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

List active courses in an account AccountsController#courses_api

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

Retrieve the list of courses in this account.

Request Parameters:

  • with_enrollments
    Optional, 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.

  • published
    Optional, Boolean

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

  • completed
    Optional, 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.

  • by_teachers[]
    Optional, Integer

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

  • by_subaccounts[]
    Optional, Integer

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

  • hide_enrollmentless_courses
    Optional, Boolean

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

  • state[]
    Optional, "created"|"claimed"|"available"|"completed"|"deleted"|"all"

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

  • enrollment_term_id
    Optional, Integer

    If set, only includes courses from the specified term.

  • search_term
    Optional, String

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

Returns a list of Courses

Update an account AccountsController#update

PUT /api/v1/accounts/:id

Update an existing account.

Request Parameters:

  • account[name]
    Optional, String

    Updates the account name

  • account[default_time_zone]
    Optional, String

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

  • account[default_storage_quota_mb]
    Optional, Integer

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

  • account[default_user_storage_quota_mb]
    Optional, Integer

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

  • account[default_group_storage_quota_mb]
    Optional, Integer

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

Example Request:

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

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:

  • account[name]
    String

    The name of the new sub-account.

  • account[default_storage_quota_mb]
    Optional, Integer

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

  • account[default_user_storage_quota_mb]
    Optional, Integer

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

  • account[default_group_storage_quota_mb]
    Optional, Integer

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

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:

  • user_id
    String

    The id of the user to promote.

  • role
    Optional, String

    The user's admin relationship with the account will be created with the given role. Defaults to 'AccountAdmin'.

  • send_confirmation
    Optional, Boolean

    Send a notification email to

    the new admin if true. Default is true.

Returns a Admin

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:

  • role
    Optional, String

    Account role to remove from the user. Defaults to 'AccountAdmin'. Any other account role must be specified explicitly.

Returns a Admin

List account admins AdminsController#index

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

List the admins in the account

Returns a list of Admins

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.

Example Request:

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

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

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

Example Response:

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

Get department-level grade data

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

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.

Example Request:

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

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

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

Example Response:

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

Get department-level statistics

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

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.

Example Request:

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

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

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

Example Response:

{
  "courses": 27,
  "teachers": 36,
  "students": 418,
  "discussion_topics": 77,
  "discussion_replies": 823,
  "media_objects": 219,
  "attachments": 1268,
  "assignments": 290,
  "submissions": 354
}

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

Example Request:

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

Example Response:

{
  "page_views": {
    "2012-01-24": {
      "general": 200,
      "grades": 25,
      "files": 5,
      "other": 10
    },
    "2012-01-27": {
      "general": 251,
      "assignments": 55,
      "pages": 6
    }
  },
  "participations": [
    "2012-01-21",
    "2012-01-27"
  ]
}

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:

  • async
    Boolean

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

Example Request:

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

Example Response:

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

Get course-level student summary data

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

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. The data is returned as a list in lexical order on the student name.

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

Example Request:

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

Example Response:

[
  {
    "id": 2346,
    "page_views": 351,
    "participations": 1,
    "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 and participation numbers grouped by day through the entire history of the course. Two hashes are returned, one for page views and one for participations, where the hash keys are dates in the format "YYYY-MM-DD".

Example Request:

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

Example Response:

{
  "page_views": {
    "2012-01-24": 19,
    "2012-01-27": 23,
  },
  "participations": [
    {
      "created_at": "2012-01-21T22:00:00-06:00",
      "url": "/path/to/canvas",
    },
    {
      "created_at": "2012-01-27T22:00:00-06:00",
      "url": "/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.

Example Request:

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

Example Response:

[
  {
    "assignment_id": 1234,
    "title": "Assignment 1",
    "points_possible": 10,
    "due_at": "2012-01-25T22:00:00-07:00",
    "unlock_at": "2012-01-20T22:00:00-07:00",
    "muted": false,
    "min_score": 2,
    "max_score": 10,
    "median": 7,
    "first_quartile": 4,
    "third_quartile": 8,
    "submission": {
      "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,
    "submission": {
      "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.

Example Request:

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

Example Response:

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

List external feeds ExternalFeedsController#index

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

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

Returns the list of External Feeds this course or group.

Example Request:

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

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:

  • url
    String

    The url to the external rss or atom feed

  • header_match
    Optional, Boolean

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

  • verbosity
    String, "full"|"truncate"|"link_only"

Example Request:

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

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.

Example Request:

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

List appointment groups AppointmentGroupsController#index

GET /api/v1/appointment_groups

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

Request Parameters:

  • scope
    Optional, String, "reservable"|"manageable"

    Defaults to "reservable"

  • context_codes[]
    Optional, String

    Array of context codes used to limit returned results.

  • include_past_appointments
    Optional, Boolean

    Defaults to false. If true, includes past appointment groups

  • include[]
    Optional, "appointments"|"child_events"|"participant_count"|"reserved_times"

    Array of additional information to include.

    "appointments"

    calendar event time slots for this appointment group

    "child_events"

    reservations of those time slots

    "participant_count"

    number of reservations

    "reserved_times"

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

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:

  • appointment_group[context_codes][]
    String

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

  • appointment_group[sub_context_codes][]
    Optional, String

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

  • appointment_group[title]
    Optional, String

    Short title for the appointment group.

  • appointment_group[description]
    Optional, String

    Longer text description of the appointment group.

  • appointment_group[location_name]
    Optional, String

    Location name of the appointment group.

  • appointment_group[location_address]
    Optional, String

    Location address.

  • appointment_group[publish]
    Optional, Boolean

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

  • appointment_group[participants_per_appointment]
    Optional, Integer

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

  • appointment_group[min_appointments_per_participant]
    Optional, Integer

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

  • appointment_group[max_appointments_per_participant]
    Optional, Integer

    Maximum number of time slots a user may register for.

  • appointment_group[new_appointments][X][]
    Optional

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

  • appointment_group[participant_visibility]
    Optional, "private"|"protected"
    "private"

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

    "protected"

    participants can see who has signed up. Defaults to "private".

Example Request:

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

Get a single appointment group AppointmentGroupsController#show

GET /api/v1/appointment_groups/:id

Returns information for a single appointment group

Request Parameters:

  • include[]
    Optional, "child_events"|"appointments"

    Array of additional information to include. Ssee include[] argument of "List appointment groups" action.

    "child_events"

    reservations of time slots time slots

    "appointments"

    will always be returned

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:

  • appointment_group[context_codes][]
    String

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

  • appointment_group[sub_context_codes][]
    Optional, String

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

  • appointment_group[title]
    Optional, String

    Short title for the appointment group.

  • appointment_group[description]
    Optional, String

    Longer text description of the appointment group.

  • appointment_group[location_name]
    Optional, String

    Location name of the appointment group.

  • appointment_group[location_address]
    Optional, String

    Location address.

  • appointment_group[publish]
    Optional, Boolean

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

  • appointment_group[participants_per_appointment]
    Optional, Integer

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

  • appointment_group[min_appointments_per_participant]
    Optional, Integer

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

  • appointment_group[max_appointments_per_participant]
    Optional, Integer

    Maximum number of time slots a user may register for.

  • appointment_group[new_appointments][X][]
    Optional

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

  • appointment_group[participant_visibility]
    Optional, "private"|"protected"
    "private"

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

    "protected"

    participants can see who has signed up. Defaults to "private".

Example Request:

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

Delete an appointment group AppointmentGroupsController#destroy

DELETE /api/v1/appointment_groups/:id

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

Request Parameters:

  • cancel_reason
    Optional, String

    Reason for deleting/canceling the appointment group.

Example Request:

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

List user participants AppointmentGroupsController#users

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

List 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:

  • registration_status
    Optional, "all"|"registered"|"registered"

    Limits results to the a given participation status, defaults to "all"

List student group participants AppointmentGroupsController#groups

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

List 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:

  • registration_status
    Optional, "all"|"registered"|"registered"

    Limits results to the a given participation status, defaults to "all"

List assignment groups AssignmentGroupsController#index

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

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

Request Parameters:

  • include[]
    String, "assignments"|"discussion_topic"|"all_dates"

    Associations to include with the group. both "discussion_topic" and "all_dates" is only valid are only valid if "assignments" is also included.

  • override_assignment_dates
    Optional, Boolean

    Apply assignment overrides for each assignment, defaults to true.

Returns a list of AssignmentGroups

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:

  • include[]
    "assignments"|"discussion_topic"

    Associations to include with the group. "discussion_topic" is only valid if "assignments" is also included.

  • override_assignment_dates
    Optional, Boolean

    Apply assignment overrides for each assignment, defaults to true.

Returns a AssignmentGroup

Create an Assignment Group AssignmentGroupsApiController#create

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

Create a new assignment group for this course.

Request Parameters:

  • name
    Optional, String

    The assignment group's name

  • position
    Optional, Integer

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

  • group_weight
    Optional, Float

    The percent of the total grade that this assignment group represents

  • rules
    Optional

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

Returns a AssignmentGroup

Edit an Assignment Group AssignmentGroupsApiController#update

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

Modify an existing Assignment Group. Accepts the same parameters as Assignment Group creation

Returns a AssignmentGroup

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:

  • move_assignment_to
    String

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

Returns a AssignmentGroup

Delete an assignment AssignmentsController#destroy

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

Delete the given assignment.

Example Request:

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

List assignments AssignmentsApiController#index

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

Returns the list of assignments for the current context.

Request Parameters:

  • include[]
    String, "submission"

    Associations to include with the assignment.

  • search_term
    Optional, String

    The partial title of the assignments to match and return.

  • override_assignment_dates
    Optional, Boolean

    Apply assignment overrides for each assignment, defaults to true.

Returns a list of Assignments

Get a single assignment AssignmentsApiController#show

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

Returns the assignment with the given id.

Request Parameters:

  • include[]
    String, "submission"

    Associations to include with the assignment.

  • override_assignment_dates
    Optional, Boolean

    Apply assignment overrides to the assignment, defaults to true.

Returns a Assignment

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:

  • assignment[name]
    String

    The assignment name.

  • assignment[position]
    Integer

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

  • assignment[submission_types][]
    String, "online_quiz"|"none"|"on_paper"|"online_quiz"|"discussion_topic"|"external_tool"|"online_upload"|"online_text_entry"|"online_url"|"media_recording"

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

    If not allowing online submissions, your options are:

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

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

    "online_upload"
    "online_text_entry"
    "online_url"
    "media_recording" (Only valid when the Kaltura plugin is enabled)
  • assignment[allowed_extensions][]
    String

    Allowed extensions if submission_types includes "online_upload"

    Example:

    allowed_extensions: ["docx","ppt"]
  • assignment[turnitin_enabled]
    Optional, Boolean

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

  • assignment[turnitin_settings]
    Optional

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

  • assignment[peer_reviews]
    Optional, Boolean

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

  • assignment[automatic_peer_reviews]
    Optional, Boolean

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

  • assignment[notify_of_update]
    Optional, Boolean

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

  • assignment[group_category_id]
    Optional, Integer

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

  • assignment[grade_group_students_individually]
    Optional, Integer

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

  • assignment[external_tool_tag_attributes]
    Optional

    Hash of attributes if submission_types is ["external_tool"] Example:

    external_tool_tag_attributes: {
      %r/ url to the external tool
      url: "http://instructure.com",
      %r/ create a new tab for the module, defaults to false.
      new_tab: false
    }
    
  • assignment[points_possible]
    Float

    The maximum points possible on the assignment.

  • assignment[grading_type]
    Optional, "pass_fail"|"percent"|"letter_grade"|"gpa_scale"|"points"

    The strategy used for grading the assignment. The assignment is ungraded if this field is omitted.

  • assignment[due_at]
    Timestamp

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

  • assignment[lock_at]
    Timestamp

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

  • assignment[unlock_at]
    Timestamp

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

  • assignment[description]
    String

    The assignment's description, supports HTML.

  • assignment[assignment_group_id]
    Integer

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

  • assignment[muted]
    Boolean

    Whether this assignment is muted. A muted assignment does not send change notifications and hides grades from students. Defaults to false.

  • assignment[assignment_overrides][]
    Optional, AssignmentOverride

    List of overrides for the assignment. NOTE: The assignment overrides feature is in beta.

  • assignment[only_visible_to_overrides]
    Optional, Boolean

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

  • assignment[published]
    Optional, Boolean

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

Returns a Assignment

Edit an assignment AssignmentsApiController#update

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

Modify an existing assignment. See the documentation for assignment creation.

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

NOTE: The assignment overrides feature is in beta.

Request Parameters:

  • assignment[grading_standard_id]
    Optional, Integer

    The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course. This will update the grading_type for the course to 'letter_grade' unless it is already 'gpa_scale'.

Returns a Assignment

List assignment overrides AssignmentOverridesController#index

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

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

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

Returns a list of AssignmentOverrides

Get a single assignment override AssignmentOverridesController#show

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

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

Returns details of the the override with the given id.

Returns a AssignmentOverride

Redirect to the assignment override for a group AssignmentOverridesController#group_alias

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

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

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

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

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

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:

  • assignment_override[student_ids][]
    Optional, Integer

    The IDs of

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

  • assignment_override[title]
    Optional

    The title of the adhoc

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

  • assignment_override[group_id]
    Optional, Integer

    The ID of the

    override's target group. If present, the following conditions must be met for the override to be successful:

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

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

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

    See Appendix: Group assignments for more info.

  • assignment_override[course_section_id]
    Optional, Integer

    The ID

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

  • assignment_override[due_at]
    Optional, Timestamp

    The day/time

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

  • assignment_override[unlock_at]
    Optional, Timestamp

    The day/time

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

  • assignment_override[lock_at]
    Optional, Timestamp

    The day/time

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

Example Request:

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

Update an assignment override AssignmentOverridesController#update

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

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:

  • assignment_override[student_ids][]
    Optional, Integer

    The IDs of the

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

  • assignment_override[title]
    Optional, String

    The title of an adhoc

    assignment override. Ignored unless the override being updated is adhoc.

  • assignment_override[due_at]
    Optional, Timestamp

    The day/time

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

  • assignment_override[unlock_at]
    Optional, Timestamp

    The day/time

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

  • assignment_override[lock_at]
    Optional, Timestamp

    The day/time

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

Example Request:

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

Delete an assignment override AssignmentOverridesController#destroy

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

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

Deletes an override and returns its former details.

Example Request:

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

Query by login. AuthenticationAuditApiController#for_login

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

List authentication events for a given login.

Request Parameters:

  • start_time
    Optional, DateTime

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

  • end_time
    Optional, Datetime

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

Query by account. AuthenticationAuditApiController#for_account

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

List authentication events for a given account.

Request Parameters:

  • start_time
    Optional, Datetime

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

  • end_time
    Optional, Datetime

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

Query by user. AuthenticationAuditApiController#for_user

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

List authentication events for a given user.

Request Parameters:

  • start_time
    Optional, Datetime

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

  • end_time
    Optional, Datetime

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

List calendar events CalendarEventsApiController#index

GET /api/v1/calendar_events

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

Request Parameters:

  • type
    Optional, String, "event"|"assignment"

    Defaults to "event"

  • start_date
    Optional, Date

    Only return events since the start_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd.

  • end_date
    Optional, Date

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

  • undated
    Optional, Boolean

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

  • all_events
    Optional, Boolean

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

  • context_codes[]
    Optional, String

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

Create a calendar event CalendarEventsApiController#create

POST /api/v1/calendar_events

Create and return a new calendar event

Request Parameters:

  • calendar_event[context_code]
    String

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

  • calendar_event[title]
    Optional, String

    Short title for the calendar event.

  • calendar_event[description]
    Optional, String

    Longer HTML description of the event.

  • calendar_event[start_at]
    Optional, DateTime

    Start date/time of the event.

  • calendar_event[end_at]
    Optional, DateTime

    End date/time of the event.

  • calendar_event[location_name]
    Optional, String

    Location name of the event.

  • calendar_event[location_address]
    Optional, String

    Location address

  • calendar_event[time_zone_edited]
    Optional, String

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

  • calendar_event[child_event_data][X][start_at]
    Optional, DateTime

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

  • calendar_event[child_event_data][X][end_at]
    Optional, DateTime

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

  • calendar_event[child_event_data][X][context_code]
    Optional, String

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

Example Request:

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

Get a single calendar event or assignment CalendarEventsApiController#show

GET /api/v1/calendar_events/:id

Returns information for a single event or assignment

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:

  • participant_id
    Optional, String

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

  • cancel_existing
    Optional, Boolean

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

Example Request:

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

Update a calendar event CalendarEventsApiController#update

PUT /api/v1/calendar_events/:id

Update and return a calendar event

Request Parameters:

  • calendar_event[context_code]
    String

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

  • calendar_event[title]
    Optional, String

    Short title for the calendar event.

  • calendar_event[description]
    Optional, String

    Longer HTML description of the event.

  • calendar_event[start_at]
    Optional, DateTime

    Start date/time of the event.

  • calendar_event[end_at]
    Optional, DateTime

    End date/time of the event.

  • calendar_event[location_name]
    Optional, String

    Location name of the event.

  • calendar_event[location_address]
    Optional, String

    Location address

  • calendar_event[time_zone_edited]
    Optional, String

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

  • calendar_event[child_event_data][X][start_at]
    Optional, DateTime

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

  • calendar_event[child_event_data][X][end_at]
    Optional, DateTime

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

  • calendar_event[child_event_data][X][context_code]
    Optional, String

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

Example Request:

curl 'https://<canvas>/api/v1/calendar_events/234.json' \
     -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:

  • cancel_reason
    Optional, String

    Reason for deleting/canceling the event.

Example Request:

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

List members of a collaboration. CollaborationsController#members

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

Examples

curl https://<canvas>/api/v1/courses/1/collaborations/1/members
Returns a list of Collaborators

List of CommMessages for a user CommMessagesApiController#index

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

GET /api/v1/comm_messages

Retrieve messages sent to a user.

Request Parameters:

  • user_id
    String

    The user id for whom you want to retrieve CommMessages

  • start_time
    Optional, DateTime

    The beginning of the time range you want to retrieve message from.

  • end_time
    Optional, DateTime

    The end of the time range you want to retrieve messages for.

Returns a list of CommMessages

List user communication channels CommunicationChannelsController#index

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

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

Example Request:

curl https://<canvas>/api/v1/users/12345/communication_channels \ 
     -H 'Authorization: Bearer <token>'
Returns a list of CommunicationChannels

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:

  • communication_channel[address]
    String

    An email address or SMS number.

  • communication_channel[type]
    String, "email"|"sms"|"push"

    The type of communication channel.

    In order to enable push notification support, the server must be properly configured (via sns.yml) to communicate with Amazon Simple Notification Services, and the developer key used to create the access token from this request must have an SNS ARN configured on it.

  • skip_confirmation
    Optional, Boolean

    Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.

Example Request:

curl https://<canvas>/api/v1/users/1/communication_channels \
     -H 'Authorization: Bearer <token>' \
     -d 'communication_channel[address]=new@example.com' \
     -d 'communication_channel[type]=email' \
Returns a CommunicationChannel

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.

Example Request:

curl https://<canvas>/api/v1/users/5/communication_channels/3
     -H 'Authorization: Bearer <token>
     -X DELETE
Returns a CommunicationChannel

List conferences ConferencesController#index

GET /api/v1/courses/:course_id/conferences

GET /api/v1/groups/:group_id/conferences

Retrieve the 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"

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

   curl 'https://<canvas>/api/v1/groups/<group_id>/conferences' \
       -H "Authorization: Bearer <token>"
Returns a list of Conferences

List content exports ContentExportsApiController#index

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

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

List the past and pending content export jobs for a course. Exports are returned newest first.

Returns a list of ContentExports

Show content export ContentExportsApiController#show

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

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

Get information about a single content export.

Returns a ContentExport

Export course content ContentExportsApiController#create

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

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

Begin a content export job for a course.

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:

  • export_type
    String, "common_cartridge"|"qti"
    "common_cartridge"

    Export the contents of the course in the Common Cartridge (.imscc) format

    "qti"

    Export quizzes in the QTI format

Returns a ContentExport

List migration issues MigrationIssuesController#index

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

Returns paginated migration issues

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues \ 
    -H 'Authorization: Bearer <token>'
Returns a list of MigrationIssues

Get a migration issue MigrationIssuesController#show

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

Returns data on an individual migration issue

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues/<id> \ 
    -H 'Authorization: Bearer <token>'
Returns a MigrationIssue

Update a migration issue MigrationIssuesController#update

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

Update the workflow_state of a migration issue

Request Parameters:

  • workflow_state
    String, "active"|"resolved"

    Set the workflow_state of the issue.

Example Request:

curl -X PUT https://<canvas>/api/v1/courses/<course_id>/content_migrations/<content_migration_id>/migration_issues/<id> \ 
     -H 'Authorization: Bearer <token>' \ 
     -F 'workflow_state=resolved'
Returns a MigrationIssue

List content migrations ContentMigrationsController#index

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

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

Returns paginated content migrations

Example Request:

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

Get a content migration ContentMigrationsController#show

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

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

Returns data on an individual content migration

Example Request:

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

Create a content migration ContentMigrationsController#create

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

POST /api/v1/courses/:course_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:

  • migration_type
    String

    The type of the migration. Use the Migrator endpoint to see all available migrators. Default allowed values: canvas_cartridge_importer, common_cartridge_importer, course_copy_importer, zip_file_importer, qti_converter, moodle_converter

  • pre_attachment[name]
    String

    Required if uploading a file. This is the first step in uploading a file to the content migration. See the File Upload Documentation for details on the file upload workflow.

  • pre_attachment[*]
    Optional

    Other file upload properties, See File Upload Documentation

  • settings[file_url]
    string

    (optional) A URL to download the file from. Must not require authentication.

  • settings[source_course_id]
    Optional, String

    The course to copy from for a course copy migration. (required if doing course copy)

  • settings[folder_id]
    Optional, String

    The folder to unzip the .zip file into for a zip_file_import.

  • settings[overwrite_quizzes]
    Optional, Boolean

    Whether to overwrite quizzes with the same identifiers between content packages.

  • settings[question_bank_id]
    Optional, Integer

    The existing question bank ID to import questions into if not specified in the content package.

  • settings[question_bank_name]
    Optional, String

    The question bank to import questions into if not specified in the content package, if both bank id and name are set, id will take precedence.

  • date_shift_options[shift_dates]
    Optional, Boolean

    Whether to shift dates

  • date_shift_options[old_start_date]
    Optional, Date

    The original start date of the source content/course

  • date_shift_options[old_end_date]
    Optional, Date

    The original end date of the source content/course

  • date_shift_options[new_start_date]
    Optional, Date

    The new start date for the content/course

  • date_shift_options[new_end_date]
    Optional, Date

    The new end date for the source content/course

  • date_shift_options[day_substitutions][X]
    Optional, Integer

    Move anything scheduled for day 'X' to the specified day. (0-Sunday, 1-Monday, 2-Tuesday, 3-Wednesday, 4-Thursday, 5-Friday, 6-Saturday)

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/content_migrations' \ 
     -F 'migration_type=common_cartridge_importer' \ 
     -F 'settings[question_bank_name]=importquestions' \ 
     -F 'date_shift_options[old_start_date]=1999-01-01' \ 
     -F 'date_shift_options[new_start_date]=2013-09-01' \ 
     -F 'date_shift_options[old_end_date]=1999-04-15' \ 
     -F 'date_shift_options[new_end_date]=2013-12-15' \ 
     -F 'date_shift_options[day_substitutions][1]=2' \ 
     -F 'date_shift_options[day_substitutions][2]=3' \ 
     -F 'date_shift_options[shift_dates]=true' \ 
     -F 'pre_attachment[name]=mycourse.imscc' \ 
     -F 'pre_attachment[size]=12345' \ 
     -H 'Authorization: Bearer <token>'
Returns a ContentMigration

Update a content migration ContentMigrationsController#update

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

PUT /api/v1/courses/:course_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. If the first upload has a problem you can supply new pre_attachment values to start the process again.

Returns a ContentMigration

List Migration Systems ContentMigrationsController#available_migrators

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

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

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

Returns a list of Migrators

List conversations ConversationsController#index

GET /api/v1/conversations

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

Request Parameters:

  • scope
    Optional, String, "unread"|"starred"|"archived"

    When set, only return conversations of the specified type. For example, set to "unread" to return only conversations that haven't been read. The default behavior is to return all non-archived conversations (i.e. read and unread).

  • filter[]
    Optional, String, course_id|group_id|user_id

    When set, only return conversations for the specified courses, groups or users. The id should be prefixed with its type, e.g. "user_123" or "course_456". Can be an array (by setting "filter[]") or single value (by setting "filter")

  • filter_mode
    optional, "and"|"or", default "or"

    When filter[] contains multiple filters, combine them with this mode, filtering conversations that at have at least all of the contexts ("and") or at least one of the contexts ("or")

  • interleave_submissions
    Boolean

    Default is false. If true, the

    message_count will also include these submission-based messages in the total. See the show action for more information.

  • include_all_conversation_ids
    Boolean

    Default is false. If true,

    the top-level element of the response will be an object rather than an array, and will have the keys "conversations" which will contain the paged conversation data, and "conversation_ids" which will contain the ids of all conversations under this scope/filter in the same order.

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) participating in the conversation. Includes current user.

  • visible

    Boolean, indicates whether the conversation is visible under the current scope and filter. This attribute is always true in the index API response, and is primarily useful in create/update responses so that you can know if the record should be displayed in the UI. The default scope is assumed, unless a scope or filter is passed to the create/update API call.

Example Response:

[
  {
    "id": 2,
    "subject": "conversations api example",
    "workflow_state": "unread",
    "last_message": "sure thing, here's the file",
    "last_message_at": "2011-09-02T12:00:00Z",
    "message_count": 2,
    "subscribed": true,
    "private": true,
    "starred": false,
    "properties": ["attachments"],
    "audience": [2],
    "audience_contexts": {"courses": {"1": ["StudentEnrollment"]}, "groups": {}},
    "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
    "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}],
    "visible": true,
    "context_name": "Canvas 101"
  }
]
Returns a list of Conversations

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:

  • recipients[]
    String

    An array of recipient ids. These may beuser ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3

  • subject
    Optional, String

    The subject of the conversation. This is ignored when reusing a conversation. Maximum length is 255 characters.

  • body
    String

    The message to be sent

  • group_conversation
    Boolean

    Defaults to false. If true, this will be a group conversation (i.e. all recipients may see all messages and replies). If false, individual private conversations will be started with each recipient.

  • attachment_ids[]
    String

    An array of attachments ids. These must be files that have been previously uploaded to the sender's "conversation attachments" folder.

  • media_comment_id
    String

    Media comment id of an audio of video file to be associated with this message.

  • media_comment_type
    String, "audio"|"video"

    Type of the associated media file

  • mode
    String, "sync"|"async"

    Determines whether the messages will be created/sent synchronously or asynchronously. Defaults to sync, and this option is ignored if this is a group conversation or there is just one recipient (i.e. it must be a bulk private message). When sent async, the response will be an empty array (batch status can be queried via the batches API)

  • scope
    Optional, String, "unread"|"starred"|"archived"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter[]
    Optional, String, course_id|group_id|user_id

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter_mode
    optional, "and"|"or", default "or"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • context_code
    Optional, String

    The course or group that is the context for this conversation. Same format as courses or groups in the recipients argument.

Get running batches ConversationsController#batches

GET /api/v1/conversations/batches

Returns any currently running conversation batches for the current user. Conversation batches are created when a bulk private message is sent asynchronously (see the mode argument to the create API action).

Example Response:

[
  {
    "id": 1,
    "subject": "conversations api example",
    "workflow_state": "created",
    "completion": 0.1234,
    "tags": [],
    "message":
    {
      "id": 1,
      "created_at": "2011-09-02T10:00:00Z",
      "body": "quick reminder, no class tomorrow",
      "author_id": 1,
      "generated": false,
      "media_comment": null,
      "forwarded_messages": [],
      "attachments": []
    }
  }
]

Get a single conversation ConversationsController#show

GET /api/v1/conversations/:id

Returns information for a single conversation. Response includes all fields that are present in the list/index action, as well as messages, submissions, and extended participant information.

Request Parameters:

  • interleave_submissions
    Boolean

    Default false. If true,

    submission data will be returned as first class messages interleaved with other messages. The submission details (comments, assignment, etc.) will be stored as the submission property on the message. Note that if set, the message_count will also include these messages in the total.

  • scope
    Optional, String, "unread"|"starred"|"archived"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter[]
    Optional, String, course_id|group_id|user_id

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter_mode
    optional, "and"|"or", default "or"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • auto_mark_as_read
    Boolean

    Default true. If true, unread

    conversations will be automatically marked as read. This will default to false in a future API release, so clients should explicitly send true if that is the desired behavior.

API response field:

  • participants

    Array of relevant users. Includes current user. If there are forwarded messages in this conversation, the authors of those messages will also be included, even if they are not participating in this conversation. Fields include:

  • messages

    Array of messages, newest first. Fields include:

    id

    The unique identifier for the message

    created_at

    The timestamp of the message

    body

    The actual message body

    author_id

    The id of the user who sent the message (see audience, participants)

    generated

    If true, indicates this is a system-generated message (e.g. "Bob added Alice to the conversation")

    media_comment

    Audio/video comment data for this message (if applicable). Fields include: display_name, content-type, media_id, media_type, url

    forwarded_messages

    If this message contains forwarded messages, they will be included here (same format as this list). Note that those messages may have forwarded messages of their own, etc.

    attachments

    Array of attachments for this message. Fields include: display_name, content-type, filename, url

  • submissions

    Array of assignment submissions having comments relevant to this conversation. These should be interleaved with the messages when displaying to the user. See the Submissions API documentation for details on the fields included. This response includes the submission_comments and assignment associations.

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "unread",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": ["attachments"],
  "audience": [2],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}, {"id": 3, "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:

  • conversation[subject]
    String

    Change the subject of this conversation

  • conversation[workflow_state]
    String, "read"|"unread"|"archived"

    Change the state of this conversation

  • conversation[subscribed]
    Boolean

    Toggle the current user's subscription to the conversation (only valid for group conversations). If unsubscribed, the user will still have access to the latest messages, but the conversation won't be automatically flagged as unread, nor will it jump to the top of the inbox.

  • conversation[starred]
    Boolean

    Toggle the starred state of the current user's view of the conversation.

  • scope
    Optional, String, "unread"|"starred"|"archived"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter[]
    Optional, String, course_id|group_id|user_id

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter_mode
    optional, "and"|"or", default "or"

    Used when generating "visible" in the API response. See the explanation under the index API action

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": ["attachments"],
  "audience": [2],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}]
}

Mark all as read ConversationsController#mark_all_as_read

POST /api/v1/conversations/mark_all_as_read

Mark all conversations as read.

Delete a conversation ConversationsController#destroy

DELETE /api/v1/conversations/:id

Delete this conversation and its messages. Note that this only deletes this user's view of the conversation.

Response includes same fields as UPDATE action

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": null,
  "last_message_at": null,
  "message_count": 0,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": []
}

Add recipients ConversationsController#add_recipients

POST /api/v1/conversations/:id/add_recipients

Add recipients to an existing group conversation. Response is similar to the GET/show action, except that omits submissions and only includes the latest message (e.g. "joe was added to the conversation by bob")

Request Parameters:

  • recipients[]
    String

    An array of recipient ids. These may be user ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": "let's talk this over with jim",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": false,
  "starred": null,
  "properties": [],
  "audience": [2, 3, 4],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}, {"id": 3, "name": "Bob Student"}, {"id": 4, "name": "Jim Admin"}],
  "messages":
    [
      {
        "id": 4,
        "created_at": "2011-09-02T12:10:00Z",
        "body": "Jim was added to the conversation by Joe TA",
        "author_id": 1,
        "generated": true,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": []
      }
    ]
}

Add a message ConversationsController#add_message

POST /api/v1/conversations/:id/add_message

Add a message to an existing conversation. Response is similar to the GET/show action, except that omits submissions and only includes the latest message (i.e. what we just sent)

An array of user ids. Defaults to all of the current conversation recipients. To explicitly send a message to no other recipients, this array should consist of the logged-in user id.

An array of message ids from this conversation to send to recipients of the new message. Recipients who already had a copy of included messages will not be affected.

Request Parameters:

  • body
    String

    The message to be sent.

  • attachment_ids[]
    String

    An array of attachments ids. These must be files that have been previously uploaded to the sender's "conversation attachments" folder.

  • media_comment_id
    String

    Media comment id of an audio of video file to be associated with this message.

  • media_comment_type
    String, "audio"|"video"

    Type of the associated media file.

  • recipients[]
    Optional, String
  • included_messages[]
    Optional, String

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "unread",
  "last_message": "let's talk this over with jim",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": false,
  "starred": null,
  "properties": [],
  "audience": [2, 3],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}, {"id": 3, "name": "Bob Student"}],
  "messages":
    [
      {
        "id": 3,
        "created_at": "2011-09-02T12:00:00Z",
        "body": "let's talk this over with jim",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": []
      }
    ]
}

Delete a message ConversationsController#remove_messages

POST /api/v1/conversations/:id/remove_messages

Delete messages from this conversation. Note that this only affects this user's view of the conversation. If all messages are deleted, the conversation will be as well (equivalent to DELETE)

Request Parameters:

  • remove[]
    String

    Array of message ids to be deleted

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 1,
  "subscribed": true,
  "private": true,
  "starred": null,
  "properties": ["attachments"]
}

Batch update conversations ConversationsController#batch_update

PUT /api/v1/conversations

Perform a change on a set of conversations. Operates asynchronously; use the progress endpoint to query the status of an operation.

Request Parameters:

  • conversation_ids[]
    String

    List of conversations to update. Limited to 500 conversations.

  • event
    String, "mark_as_read"|"mark_as_unread"|"star"|"unstar"|"archive"|"destroy"

    The action to take on each conversation.

Example Request:

curl https://<canvas>/api/v1/conversations \ 
  -X PUT \ 
  -H 'Authorization: Bearer <token>' \ 
  -d 'event=mark_as_read' \ 
  -d 'conversation_ids[]=1' \ 
  -d 'conversation_ids[]=2'
Returns a Progress

Find recipients ConversationsController#find_recipients

GET /api/v1/conversations/find_recipients

Deprecated, see the Find recipients endpoint in the Search API

Unread count ConversationsController#unread_count

GET /api/v1/conversations/unread_count

Get the number of unread conversations for the current user

Example Response:

{'unread_count': '7'}

Query by course. CourseAuditApiController#for_course

GET /api/v1/audit/course/courses/:course_id

List course change events for a given course.

Request Parameters:

  • start_time
    Optional, DateTime

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

  • end_time
    Optional, Datetime

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

Returns a list of CourseEvents

List your courses CoursesController#index

GET /api/v1/courses

Returns the list of active courses for the current user.

Request Parameters:

  • enrollment_type
    Optional, String, "teacher"|"student"|"ta"|"observer"|"designer"

    When set, only return courses where the user is enrolled as this type. For example, set to "teacher" to return only courses where the user is enrolled as a Teacher. This argument is ignored if enrollment_role is given.

  • enrollment_role
    Optional, String

    When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the Add Role API or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.

  • include[]
    String, "needs_grading_count"|"syllabus_body"|"total_scores"|"term"|"course_progress"
    • "needs_grading_count": Optional information to include with each Course. When needs_grading_count is given, and the current user has grading rights, the total number of submissions needing grading for all assignments is returned.

    • "syllabus_body": Optional information to include with each Course. When syllabus_body is given the user-generated html for the course syllabus is returned.

    • "total_scores": Optional information to include with each Course. When total_scores is given, any enrollments with type 'student' will also include the fields 'calculated_current_score', 'calculated_final_score', 'calculated_current_grade', and 'calculated_final_grade'. calculated_current_score is the student's score in the course, ignoring ungraded assignments. calculated_final_score is the student's score in the course including ungraded assignments with a score of 0. calculated_current_grade is the letter grade equivalent of calculated_current_score (if available). calculated_final_grade is the letter grade equivalent of calculated_final_score (if available). This argument is ignored if the course is configured to hide final grades.

    • "term": Optional information to include with each Course. When term is given, the information for the enrollment term for each course is returned.

    • "course_progress": Optional information to include with each Course. When course_progress is given, each course will include a 'course_progress' object with the fields: 'requirement_count', an integer specifying the total number of requirements in the course, 'requirement_completed_count', an integer specifying the total number of requirements in this course that have been completed, and 'next_requirement_url', a string url to the next requirement item, and 'completed_at', the date the course was completed (null if incomplete). 'next_requirement_url' will be null if all requirements have been completed or the current module does not require sequential progress. "course_progress" will return an error message if the course is not module based or the user is not enrolled as a student in the course.

  • state[]
    Optional, String, "unpublished"|"available"|"completed"|"deleted"

    If set, only return courses that are in the given state(s). By default, "available" is returned for students and observers, and anything except "deleted", for all other enrollment types

Returns a list of Courses

Create a new course CoursesController#create

POST /api/v1/accounts/:account_id/courses

Create a new course

Request Parameters:

  • account_id
    Integer

    The unique ID of the account to create to course under.

  • course[name]
    Optional, String

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

  • course[course_code]
    Optional, String

    The course code for the course.

  • course[start_at]
    Optional, DateTime

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

  • course[end_at]
    Optional, DateTime

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

  • course[license]
    Optional, String

    The name of the licensing. Should be one of the following abbreviations (a descriptive name is included in parenthesis for reference):

    • 'private' (Private Copyrighted)

    • 'cc_by_nc_nd' (CC Attribution Non-Commercial No Derivatives)

    • 'cc_by_nc_sa' (CC Attribution Non-Commercial Share Alike)

    • 'cc_by_nc' (CC Attribution Non-Commercial)

    • 'cc_by_nd' (CC Attribution No Derivatives)

    • 'cc_by_sa' (CC Attribution Share Alike)

    • 'cc_by' (CC Attribution)

    • 'public_domain' (Public Domain).

  • course[is_public]
    Optional, Boolean

    Set to true if course if public.

  • course[public_syllabus]
    Optional, Boolean

    Set to true to make the course syllabus public.

  • course[public_description]
    Optional, String

    A publicly visible description of the course.

  • course[allow_student_wiki_edits]
    Optional, Boolean

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

  • course[allow_wiki_comments]
    Optional, Boolean

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

  • course[allow_student_forum_attachments]
    Optional, Boolean

    If true, students can attach files to forum posts.

  • course[open_enrollment]
    Optional, Boolean

    Set to true if the course is open enrollment.

  • course[self_enrollment]
    Optional, Boolean

    Set to true if the course is self enrollment.

  • course[restrict_enrollments_to_course_dates]
    Optional, Boolean

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

  • course[enroll_me]
    Optional, Boolean

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

  • course[term_id]
    Optional, Integer

    The unique ID of the term to create to course in.

  • course[sis_course_id]
    Optional, String

    The unique SIS identifier.

  • course[hide_final_grades]
    Optional, Boolean

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

  • course[apply_assignment_group_weights]
    Optional, Boolean

    Set to true to weight final grade based on assignment groups percentages.

  • offer
    Optional, Boolean

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

  • course[syllabus_body]
    Optional, String

    The syllabus body for the course

Returns a Course

Upload a file CoursesController#create_file

POST /api/v1/courses/:course_id/files

Upload a file to the course.

This API endpoint is the first step in uploading a file to a course. See the File Upload Documentation for details on the file upload workflow.

Only those with the "Manage Files" permission on a course can upload files to the course. By default, this is Teachers, TAs and Designers.

List students CoursesController#students

GET /api/v1/courses/:course_id/students

Returns the list of students enrolled in this course.

DEPRECATED: Please use the course users endpoint and pass "student" as the enrollment_type.

Returns a list of Users

List users in course CoursesController#users

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

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

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

Request Parameters:

  • search_term
    Optional, String

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

  • enrollment_type
    Optional, String, "teacher"|"student"|"ta"|"observer"|"designer"

    When set, only return users where the user is enrolled as this type. This argument is ignored if enrollment_role is given.

  • enrollment_role
    Optional, String

    When set, only return users enrolled with the specified course-level role. This can be a role created with the Add Role API or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.

  • include[]
    String, "email"|"enrollments"|"locked"|"avatar_url"|"test_student"
    • "email": Optional user email.

    • "enrollments":

    Optionally include with each Course the user's current and invited enrollments. If the user is enrolled as a student, and the account has permission to manage or view all grades, each enrollment will include a 'grades' key with 'current_score', 'final_score', 'current_grade' and 'final_grade' values.

    • "locked": Optionally include whether an enrollment is locked.

    • "avatar_url": Optionally include avatar_url.

    • "test_student": Optionally include the course's Test Student,

    if present. Default is to not include Test Student.

  • user_id
    Optional, String

    If included, the user will be queried and if the user is part of the users set, the page parameter will be modified so that the page containing user_id will be returned.

Returns a list of Users

List recently logged in students CoursesController#recent_students

GET /api/v1/courses/:course_id/recent_students

Returns the list of users in this course, ordered by how recently they have logged in. The records include the 'last_login' field which contains a timestamp of the last time that user logged into canvas. The querying user must have the 'View usage reports' permission.

Example Request:

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

Get single user CoursesController#user

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

Return information on a single user.

Accepts the same include[] parameters as the :users: action, and returns a single user with the same fields as that action.

Returns a User

Preview processed html CoursesController#preview_html

POST /api/v1/courses/:course_id/preview_html

Preview html content processed for this course

Request Parameters:

  • html

    The html content to process

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/preview_html \
     -F 'html=<p><badhtml></badhtml>processed html</p>' \
     -H 'Authorization: Bearer <token>'

Example Response:

{
  "html": "<p>processed html</p>"
}

Course activity stream CoursesController#activity_stream

GET /api/v1/courses/:course_id/activity_stream

Returns the current user's course-specific activity stream, paginated.

For full documentation, see the API documentation for the user activity stream, in the user api.

Course activity stream summary CoursesController#activity_stream_summary

GET /api/v1/courses/:course_id/activity_stream/summary

Returns a summary of the current user's course-specific activity stream.

For full documentation, see the API documentation for the user activity stream summary, in the user api.

Course TODO items CoursesController#todo_items

GET /api/v1/courses/:course_id/todo

Returns the current user's course-specific todo items.

For full documentation, see the API documentation for the user todo items, in the user api.

Conclude a course CoursesController#destroy

DELETE /api/v1/courses/:id

Delete or conclude an existing course

Request Parameters:

  • event
    String, "delete"|"conclude"

    The action to take on the course.

Get course settings CoursesController#settings

GET /api/v1/courses/:course_id/settings

Returns some of a course's settings.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/settings \
  -X GET \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "allow_student_discussion_topics": true,
  "allow_student_forum_attachments": false,
  "allow_student_discussion_editing": true
}

Update course settings CoursesController#update_settings

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

Can update the following course settings:

Request Parameters:

  • allow_student_discussion_topics
    Boolean
  • allow_student_forum_attachments
    Boolean
  • allow_student_discussion_editing
    Boolean

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/settings \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'allow_student_discussion_topics=false'

Get a single course CoursesController#show

GET /api/v1/courses/:id

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

Return information on a single course.

Accepts the same include[] parameters as the list action plus:

Request Parameters:

  • include[]
    String, "all_courses"|"permissions"
    • "all_courses": Also search recently deleted courses.

    • "permissions": Include permissions the current user has for the course.

Returns a Course

Update a course CoursesController#update

PUT /api/v1/courses/:id

Update an existing course.

For possible arguments, see the Courses#create documentation (note: the enroll_me param is not allowed in the update action).

Additional arguments available for Courses#update

Request Parameters:

  • course[grading_standard_id]
    Optional, Integer

    The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'course[name]=New course name' \
  -d 'course[start_at]=2012-05-05T00:00:00Z'

Example Response:

{
  "name": "New course name",
  "course_code": "COURSE-001",
  "start_at": "2012-05-05T00:00:00Z",
  "end_at": "2012-08-05T23:59:59Z",
  "sis_course_id": "12345"
}

Update courses CoursesController#batch_update

PUT /api/v1/accounts/:account_id/courses

Update multiple courses in an account. Operates asynchronously; use the progress endpoint to query the status of an operation.

Request Parameters:

  • course_ids[]

    List of ids of courses to update. At most 500 courses may be updated in one call.

  • event

    The action to take on each course. Must be one of 'offer', 'conclude', 'delete', or 'undelete'.

    • 'offer' makes a course visible to students. This action is also called "publish" on the web site.

    • 'conclude' prevents future enrollments and makes a course read-only for all participants. The course still appears in prior-enrollment lists.

    • 'delete' completely removes the course from the web site (including course menus and prior-enrollment lists). All enrollments are deleted. Course content may be physically deleted at a future date.

    • 'undelete' attempts to recover a course that has been deleted. (Recovery is not guaranteed; please conclude rather than delete a course if there is any possibility the course will be used again.) The recovered course will be unpublished. Deleted enrollments will not be recovered.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/courses \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'event=offer' \
  -d 'course_ids[]=1' \
  -d 'course_ids[]=2'
Returns a Progress

Get course copy status ContentImportsController#copy_course_status

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

DEPRECATED: Please use the Content Migrations API

Retrieve the status of a course copy

API response field:

  • id

    The unique identifier for the course copy.

  • created_at

    The time that the copy was initiated.

  • progress

    The progress of the copy as an integer. It is null before the copying starts, and 100 when finished.

  • workflow_state

    The current status of the course copy. Possible values: "created", "started", "completed", "failed"

  • status_url

    The url for the course copy status API endpoint.

Example Response:

{'progress':100, 'workflow_state':'completed', 'id':257, 'created_at':'2011-11-17T16:50:06Z', 'status_url':'/api/v1/courses/9457/course_copy/257'}

Copy course content ContentImportsController#copy_course_content

POST /api/v1/courses/:course_id/course_copy

DEPRECATED: Please use the Content Migrations API

Copies content from one course into another. The default is to copy all course content. You can control specific types to copy by using either the 'except' option or the 'only' option.

The response is the same as the course copy status endpoint

Request Parameters:

  • source_course
    String

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

  • except[]
    String, "course_settings"|"assignments"|"external_tools"|"files"|"topics"|"calendar_events"|"quizzes"|"wiki_pages"|"modules"|"outcomes"

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

  • only[]
    String, "course_settings"|"assignments"|"external_tools"|"files"|"topics"|"calendar_events"|"quizzes"|"wiki_pages"|"modules"|"outcomes"

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

List custom gradebook columns CustomGradebookColumnsApiController#index

GET /api/v1/courses/:course_id/custom_gradebook_columns

List all custom gradebook columns for a course

Returns a list of CustomColumns

Create a custom gradebook column CustomGradebookColumnsApiController#create

POST /api/v1/courses/:course_id/custom_gradebook_columns

Create a custom gradebook column

Request Parameters:

  • column[title]
    String
  • column[position]
    Int

    The position of the column relative to other custom columns

  • column[hidden]
    Optional, Boolean

    Hidden columns are not displayed in the gradebook

  • column[teacher_notes]
    Optional, Boolean

    Set this if the column is created by a teacher. The gradebook only supports one teacher_notes column.

Returns a CustomColumn

Update a custom gradebook column CustomGradebookColumnsApiController#update

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

Accepts the same parameters as custom gradebook column creation

Returns a CustomColumn

Delete a custom gradebook column CustomGradebookColumnsApiController#destroy

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

Permanently deletes a custom column and its associated data

Returns a CustomColumn

Reorder custom columns CustomGradebookColumnsApiController#reorder

POST /api/v1/courses/:course_id/custom_gradebook_columns/reorder

Puts the given columns in the specified order

200 OK is returned if successful

Request Parameters:

  • order[]
    Required, Integer

List entries for a column CustomGradebookColumnDataApiController#index

GET /api/v1/courses/:course_id/custom_gradebook_columns/:id/data

This does not list entries for students without associated data.

Returns a list of ColumnData

Update column data CustomGradebookColumnDataApiController#update

PUT /api/v1/courses/:course_id/custom_gradebook_columns/:id/data/:user_id

Set the content of a custom column

Request Parameters:

  • column_data[content]
    String

    Column content. Setting this to blank will delete the datum object.

Returns a ColumnDatum

List discussion topics DiscussionTopicsController#index

GET /api/v1/courses/:course_id/discussion_topics

GET /api/v1/groups/:group_id/discussion_topics

Returns the paginated list of discussion topics for this course or group.

Request Parameters:

  • order_by
    String, "position"|"recent_activity"

    Determines the order of the discussion topic list. Defaults to "position".

  • scope
    Optional, String, "locked"|"unlocked"|"pinned"|"unpinned"

    Only return discussion topics in the given state(s). Defaults to including all topics. Filtering is done after pagination, so pages may be smaller than requested if topics are filtered. Can pass multiple states as comma separated string.

  • only_announcements
    Optional, Boolean

    Return announcements instead of discussion topics. Defaults to false

  • search_term
    Optional, String

    The partial title of the discussion topics to match and return.

Example Request:

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

Create a new discussion topic DiscussionTopicsController#create

POST /api/v1/courses/:course_id/discussion_topics

POST /api/v1/groups/:group_id/discussion_topics

POST /api/v1/collection_items/:collection_item_id/discussion_topics

Create an new discussion topic for the course or group.

Request Parameters:

  • title
    String
  • message
    String
  • discussion_type
    String
  • published
    Optional, Boolean

    Whether this topic is published (true) or draft state (false). Only teachers and TAs have the ability to create draft state topics.

  • delayed_post_at
    Optional, DateTime

    If a timestamp is given, the topic will not be published until that time.

  • lock_at
    Optional, DateTime

    If a timestamp is given, the topic will be scheduled to lock at the provided timestamp. If the timestamp is in the past, the topic will be locked.

  • podcast_enabled
    Boolean

    If true, the topic will have an associated podcast feed.

  • podcast_has_student_posts
    Boolean

    If true, the podcast will include posts from students as well. Implies podcast_enabled.

  • require_initial_post
    Boolean

    If true then a user may not respond to other replies until that user has made an initial reply. Defaults to false.

  • assignment
    Assignment

    To create an assignment discussion, pass the assignment parameters as a sub-object. See the Create an Assignment API for the available parameters. The name parameter will be ignored, as it's taken from the discussion title. If you want to make a discussion that was an assignment NOT an assignment, pass set_assignment = false as part of the assignment object

  • is_announcement
    Boolean

    If true, this topic is an announcement. It will appear in the announcement's section rather than the discussions section. This requires announcment-posting permissions.

  • position_after
    String

    By default, discussions are sorted chronologically by creation date, you can pass the id of another topic to have this one show up after the other when they are listed.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics \ 
    -F title='my topic' \ 
    -F message='initial message' \ 
    -F podcast_enabled=1 \ 
    -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics \ 
    -F title='my assignment topic' \ 
    -F message='initial message' \ 
    -F assignment[points_possible]=15 \ 
    -H 'Authorization: Bearer <token>'

Update a topic DiscussionTopicsController#update

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id

PUT /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id

Accepts the same parameters as create

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id> \ 
    -F title='This will be positioned after Topic #1234' \ 
    -F position_after=1234 \ 
    -H 'Authorization: Bearer <token>'

Delete a topic DiscussionTopicsController#destroy

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id

DELETE /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id

Deletes the discussion topic. This will also delete the assignment, if it's an assignment discussion.

Example Request:

curl -X DELETE https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id> \ 
     -H 'Authorization: Bearer <token>'

Reorder pinned topics DiscussionTopicsController#reorder

POST /api/v1/courses/:course_id/discussion_topics/reorder

POST /api/v1/groups/:group_id/discussion_topics/reorder

POST /api/v1/collection_items/:collection_item_id/discussion_topics/reorder

Puts the pinned discussion topics in the specified order. All pinned topics should be included.

Request Parameters:

  • order[]
    Required, Integer

    The ids of the pinned discussion topics in the desired order. (For example, "order=104,102,103".)

Update an entry DiscussionEntriesController#update

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:id

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:id

PUT /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries/:id

Update an existing discussion entry.

The entry must have been created by the current user, or the current user must have admin rights to the discussion. If the edit is not allowed, a 401 will be returned.

Request Parameters:

  • message
    String

    The updated body of the entry.

Example Request:

curl -X PUT 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>' \
     -F 'message=<message>' \ 
     -H "Authorization: Bearer <token>"

Delete an entry DiscussionEntriesController#destroy

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:id

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:id

DELETE /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries/:id

Delete a discussion entry.

The entry must have been created by the current user, or the current user must have admin rights to the discussion. If the delete is not allowed, a 401 will be returned.

The discussion will be marked deleted, and the user_id and message will be cleared out.

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>' \
     -H "Authorization: Bearer <token>"

Get a single topic DiscussionTopicsApiController#show

GET /api/v1/courses/:course_id/discussion_topics/:topic_id

GET /api/v1/groups/:group_id/discussion_topics/:topic_id

GET /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id

Returns data on an individual discussion topic. See the List action for the response formatting.

Example Request:

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

Get the full topic DiscussionTopicsApiController#view

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/view

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/view

GET /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/view

Return a cached structure of the discussion topic, containing all entries, their authors, and their message bodies.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body 'require_initial_post'.

In some rare situations, this cached structure may not be available yet. In that case, the server will respond with a 503 error, and the caller should try again soon.

The response is an object containing the following keys:

  • "participants": A list of summary information on users who have posted to the discussion. Each value is an object containing their id, display_name, and avatar_url.

  • "unread_entries": A list of entry ids that are unread by the current user. this implies that any entry not in this list is read.

  • "forced_entries": A list of entry ids that have forced_read_state set to true. This flag is meant to indicate the entry's read_state has been manually set to 'unread' by the user, so the entry should not be automatically marked as read.

  • "view": A threaded view of all the entries in the discussion, containing the id, user_id, and message.

  • "new_entries": Because this view is eventually consistent, it's possible that newly created or updated entries won't yet be reflected in the view. If the application wants to also get a flat list of all entries not yet reflected in the view, pass include_new_entries=1 to the request and this array of entries will be returned. These entries are returned in a flat array, in ascending created_at order.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/view' \
     -H "Authorization: Bearer <token>"

Example Response:

{
  "unread_entries": [1,3,4],
  "forced_entries": [1],
  "participants": [
    { "id": 10, "display_name": "user 1", "avatar_image_url": "https://...", "html_url": "https://..." },
    { "id": 11, "display_name": "user 2", "avatar_image_url": "https://...", "html_url": "https://..." }
  ],
  "view": [
    { "id": 1, "user_id": 10, "parent_id": null, "message": "...html text...", "replies": [
      { "id": 3, "user_id": 11, "parent_id": 1, "message": "...html....", "replies": [...] }
    ]},
    { "id": 2, "user_id": 11, "parent_id": null, "message": "...html..." },
    { "id": 4, "user_id": 10, "parent_id": null, "message": "...html..." }
  ]
}

Post an entry DiscussionTopicsApiController#add_entry

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/entries

POST /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries

Create a new entry in a discussion topic. Returns a json representation of the created entry (see documentation for 'entries' method) on success.

Request Parameters:

  • message
    String

    The body of the entry.

  • attachment
    Optional

    a multipart/form-data form-field-style

    attachment. Attachments larger than 1 kilobyte are subject to quota restrictions.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries.json' \
     -F 'message=<message>' \ 
     -F 'attachment=@<filename>' \ 
     -H "Authorization: Bearer <token>"

List topic entries DiscussionTopicsApiController#entries

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entries

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entries

GET /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries

Retrieve the (paginated) top-level entries in a discussion topic.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body 'require_initial_post'.

Will include the 10 most recent replies, if any, for each entry returned.

If the topic is a root topic with children corresponding to groups of a group assignment, entries from those subtopics for which the user belongs to the corresponding group will be returned.

Ordering of returned entries is newest-first by posting timestamp (reply activity is ignored).

API response field:

  • id

    The unique identifier for the entry.

  • user_id

    The unique identifier for the author of the entry.

  • editor_id

    The unique user id of the person to last edit the entry, if different than user_id.

  • user_name

    The name of the author of the entry.

  • message

    The content of the entry.

  • read_state

    The read state of the entry, "read" or "unread".

  • forced_read_state

    Whether the read_state was forced (was set manually)

  • created_at

    The creation time of the entry, in ISO8601 format.

  • updated_at

    The updated time of the entry, in ISO8601 format.

  • attachment

    JSON representation of the attachment for the entry, if any. Present only if there is an attachment.

  • attachments

    Deprecated. Same as attachment, but returned as a one-element array. Present only if there is an attachment.

  • recent_replies

    The 10 most recent replies for the entry, newest first. Present only if there is at least one reply.

  • has_more_replies

    True if there are more than 10 replies for the entry (i.e., not all were included in this response). Present only if there is at least one reply.

Example Response:

[ {
    "id": 1019,
    "user_id": 7086,
    "user_name": "nobody@example.com",
    "message": "Newer entry",
    "read_state": "read",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:33:29Z",
    "attachment": {
      "content-type": "unknown/unknown",
      "url": "http://www.example.com/files/681/download?verifier=JDG10Ruitv8o6LjGXWlxgOb5Sl3ElzVYm9cBKUT3",
      "filename": "content.txt",
      "display_name": "content.txt" } },
  {
    "id": 1016,
    "user_id": 7086,
    "user_name": "nobody@example.com",
    "message": "first top-level entry",
    "read_state": "unread",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:32:29Z",
    "recent_replies": [
      {
        "id": 1017,
        "user_id": 7086,
        "user_name": "nobody@example.com",
        "message": "Reply message",
        "created_at": "2011-11-03T21:32:29Z"
      } ],
    "has_more_replies": false } ]

Post a reply DiscussionTopicsApiController#add_reply

POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies

POST /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/replies

POST /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries/:entry_id/replies

Add a reply to an entry in a discussion topic. Returns a json representation of the created reply (see documentation for 'replies' method) on success.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body 'require_initial_post'.

Request Parameters:

  • message
    String

    The body of the entry.

  • attachment
    Optional

    a multipart/form-data form-field-style

    attachment. Attachments larger than 1 kilobyte are subject to quota restrictions.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/replies.json' \
     -F 'message=<message>' \ 
     -F 'attachment=@<filename>' \ 
     -H "Authorization: Bearer <token>"

List entry replies DiscussionTopicsApiController#replies

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/replies

GET /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries/:entry_id/replies

Retrieve the (paginated) replies to a top-level entry in a discussion topic.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body 'require_initial_post'.

Ordering of returned entries is newest-first by creation timestamp.

API response field:

  • id

    The unique identifier for the reply.

  • user_id

    The unique identifier for the author of the reply.

  • editor_id

    The unique user id of the person to last edit the entry, if different than user_id.

  • user_name

    The name of the author of the reply.

  • message

    The content of the reply.

  • read_state

    The read state of the entry, "read" or "unread".

  • forced_read_state

    Whether the read_state was forced (was set manually)

  • created_at

    The creation time of the reply, in ISO8601 format.

Example Response:

[ {
    "id": 1015,
    "user_id": 7084,
    "user_name": "nobody@example.com",
    "message": "Newer message",
    "read_state": "read",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:27:44Z" },
  {
    "id": 1014,
    "user_id": 7084,
    "user_name": "nobody@example.com",
    "message": "Older message",
    "read_state": "unread",
    "forced_read_state": false,
    "created_at": "2011-11-03T21:26:44Z" } ]

List entries DiscussionTopicsApiController#entry_list

GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entry_list

GET /api/v1/groups/:group_id/discussion_topics/:topic_id/entry_list

GET /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entry_list

Retrieve a paginated list of discussion entries, given a list of ids.

May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body 'require_initial_post'.

Request Parameters:

  • ids[]
    String

    A list of entry ids to retrieve. Entries will be returned in id order, smallest id first.

API response field:

  • id

    The unique identifier for the reply.

  • user_id

    The unique identifier for the author of the reply.

  • user_name

    The name of the author of the reply.

  • message

    The content of the reply.

  • read_state

    The read state of the entry, "read" or "unread".

  • forced_read_state

    Whether the read_state was forced (was set manually)

  • created_at

    The creation time of the reply, in ISO8601 format.

  • deleted

    If the entry has been deleted, returns true. The user_id, user_name, and message will not be returned for deleted entries.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entry_list?ids[]=1&ids[]=2&ids[]=3' \
     -H "Authorization: Bearer <token>"

Example Response:

[
  { ... entry 1 ... },
  { ... entry 2 ... },
  { ... entry 3 ... },
]

Mark topic as read DiscussionTopicsApiController#mark_topic_read

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/read

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/read

PUT /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/read

Mark the initial text of the discussion topic as read.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read.json' \
     -X PUT \ 
     -H "Authorization: Bearer <token>" \ 
     -H "Content-Length: 0"

Mark topic as unread DiscussionTopicsApiController#mark_topic_unread

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/read

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/read

DELETE /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/read

Mark the initial text of the discussion topic as unread.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read.json' \
     -X DELETE \ 
     -H "Authorization: Bearer <token>"

Mark all entries as read DiscussionTopicsApiController#mark_all_read

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/read_all

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/read_all

PUT /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/read_all

Mark the discussion topic and all its entries as read.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

  • forced_read_state
    Optional, Boolean

    A boolean value to set all of the entries' forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read_all.json' \
     -X PUT \ 
     -H "Authorization: Bearer <token>" \ 
     -H "Content-Length: 0"

Mark all entries as unread DiscussionTopicsApiController#mark_all_unread

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/read_all

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/read_all

DELETE /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/read_all

Mark the discussion topic and all its entries as unread.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

  • forced_read_state
    Optional, Boolean

    A boolean value to set all of the entries' forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/read_all.json' \
     -X DELETE \ 
     -H "Authorization: Bearer <token>"

Mark entry as read DiscussionTopicsApiController#mark_entry_read

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/read

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/read

PUT /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries/:entry_id/read

Mark a discussion entry as read.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

  • forced_read_state
    Optional, Boolean

    A boolean value to set the entry's forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/read.json' \
     -X PUT \ 
     -H "Authorization: Bearer <token>"\ 
     -H "Content-Length: 0"

Mark entry as unread DiscussionTopicsApiController#mark_entry_unread

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/read

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/entries/:entry_id/read

DELETE /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/entries/:entry_id/read

Mark a discussion entry as unread.

No request fields are necessary.

On success, the response will be 204 No Content with an empty body.

Request Parameters:

  • forced_read_state
    Optional, Boolean

    A boolean value to set the entry's forced_read_state. No change is made if this argument is not specified.

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/read.json' \
     -X DELETE \ 
     -H "Authorization: Bearer <token>"

Subscribe to a topic DiscussionTopicsApiController#subscribe_topic

PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed

PUT /api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed

PUT /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/subscribed

Subscribe to a topic to receive notifications about new entries

On success, the response will be 204 No Content with an empty body

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/subscribed.json' \
     -X PUT \ 
     -H "Authorization: Bearer <token>" \ 
     -H "Content-Length: 0"

Unsubscribe from a topic DiscussionTopicsApiController#unsubscribe_topic

DELETE /api/v1/courses/:course_id/discussion_topics/:topic_id/subscribed

DELETE /api/v1/groups/:group_id/discussion_topics/:topic_id/subscribed

DELETE /api/v1/collection_items/:collection_item_id/discussion_topics/:topic_id/subscribed

Unsubscribe from a topic to stop receiving notifications about new entries

On success, the response will be 204 No Content with an empty body

Example Request:

curl 'https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/subscribed.json' \
     -X DELETE \ 
     -H "Authorization: Bearer <token>"

List enrollment terms TermsApiController#index

GET /api/v1/accounts/:account_id/terms

Return all of the terms in the account. Account must be a root account and requires permission to manage the account (when called on non-root accounts, will be directed to the appropriate root account).

Request Parameters:

  • workflow_state[]
    Optional, String, 'active'| 'deleted'| 'all'

    If set, only returns terms that are in the given state. Defaults to 'active'.

Returns a list of EnrollmentTerms

List enrollments EnrollmentsApiController#index

GET /api/v1/courses/:course_id/enrollments

GET /api/v1/sections/:section_id/enrollments

GET /api/v1/users/:user_id/enrollments

Depending on the URL given, return either (1) all of the enrollments in a course, (2) all of the enrollments in a section or (3) all of a user's enrollments. This includes student, teacher, TA, and observer enrollments.

If a user has multiple enrollments in a context (e.g. as a teacher and a student or in multiple course sections), each enrollment will be listed separately.

note: Currently, only an admin user can return other users' enrollments. A user can, however, return his/her own enrollments.

Request Parameters:

  • type[]
    String

    A list of enrollment types to return. Accepted values are 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'DesignerEnrollment', and 'ObserverEnrollment.' If omitted, all enrollment types are returned. This argument is ignored if `role` is given.

  • role[]
    String

    A list of enrollment roles to return. Accepted values include course-level roles created by the Add Role API as well as the base enrollment types accepted by the `type` argument above.

  • state[]
    String, "active"|"invited"|"creation_pending"|"deleted"|"rejected"|"completed"|"inactive"

    Filter by enrollment state. If omitted, 'active' and 'invited' enrollments are returned.

Returns a list of Enrollments

Enroll a user EnrollmentsApiController#create

POST /api/v1/courses/:course_id/enrollments

POST /api/v1/sections/:section_id/enrollments

Create a new user enrollment for a course or section.

Request Parameters:

  • enrollment[user_id]
    String

    The ID of the user to be enrolled in the course.

  • enrollment[type]
    String, "StudentEnrollment"|"TeacherEnrollment"|"TaEnrollment"|"ObserverEnrollment"|"DesignerEnrollment"

    Enroll the user as a student, teacher, TA, observer, or designer. If no value is given, the type will be inferred by enrollment if supplied, otherwise 'StudentEnrollment' will be used.

  • enrollment[role]
    Optional, String

    Assigns a custom course-level role to the user.

  • enrollment[enrollment_state]
    Optional, String, "active"|"invited"

    If set to 'active,' student will be immediately enrolled in the course. Otherwise they will be required to accept a course invitation. Default is 'invited.'

  • enrollment[course_section_id]
    Optional, Integer

    The ID of the course section to enroll the student in. If the section-specific URL is used, this argument is redundant and will be ignored.

  • enrollment[limit_privileges_to_course_section]
    Optional, Boolean

    If a teacher or TA enrollment, teacher/TA will be restricted to the section given by course_section_id.

  • enrollment[notify]
    Optional, Boolean

    If true, a notification will be sent to the enrolled user. Notifications are not sent by default.

  • enrollment[self_enrollment_code]
    Optional, String

    If the current user is not allowed to manage enrollments in this course, but the course allows self-enrollment, the user can self- enroll as a student in the default section by passing in a valid code. When self-enrolling, the user_id must be 'self'. The enrollment_state will be set to 'active' and all other arguments will be ignored.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments \
  -X POST \
  -F 'user_id=1' \
  -F 'type=StudentEnrollment' \
  -F 'enrollment_state=active' \
  -F 'course_section_id=1' \
  -F 'limit_privileges_to_course_section=true' \
  -F 'notify=false'

curl https://<canvas>/api/v1/courses/:course_id/enrollments \
  -X POST \
  -F 'user_id=2' \
  -F 'type=StudentEnrollment'
Returns a Enrollment

Conclude an enrollment EnrollmentsApiController#destroy

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

Delete or conclude an enrollment.

Request Parameters:

  • task
    String, "conclude"|"delete"

    The action to take on the enrollment.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id \ 
  -X DELETE \ 
  -F 'task=conclude'
Returns a Enrollment

List external tools ExternalToolsController#index

GET /api/v1/courses/:course_id/external_tools

GET /api/v1/accounts/:account_id/external_tools

Returns the paginated list of external tools for the current context. See the get request docs for a single tool for a list of properties on an external tool.

Request Parameters:

  • search_term
    Optional, String

    The partial name of the tools to match and return.

Example Response:

[
 {
   "id":1,
   "name":"BLTI Example",
   "description":"This is for cool things"
   "url":"http://www.example.com/ims/lti",
   "domain":null,
   "privacy_level":anonymous
   "consumer_key":null,
   "created_at":"2037-07-21T13:29:31Z",
   "updated_at":"2037-07-28T19:38:31Z",
   "custom_fields":{"key":"value"},
   "account_navigation":{"url":"...", "text":"..."},
   "user_navigation":{"url":"...", "text":"..."},
   "course_navigation":{"url":"...", "text":"...", "visibility":"members", "default":true},
   "editor_button":{"url":"...", "text":"...", "selection_width":50, "selection_height":50, "icon_url":"..."},
   "resource_selection":{"url":"...", "text":"...", "selection_width":50, "selection_height":50}
 },
 {
   "id":2,
   "name":"Another BLTI Example",
   "description":"This one isn't very cool."
   "url":null,
   "domain":"example.com",
   "privacy_level":anonymous
   "consumer_key":null,
   "created_at":"2037-07-21T13:29:31Z",
   "updated_at":"2037-07-28T19:38:31Z"
 }
]

Get a sessionless launch url for an external tool. ExternalToolsController#generate_sessionless_launch

GET /api/v1/courses/:course_id/external_tools/sessionless_launch

GET /api/v1/accounts/:account_id/external_tools/sessionless_launch

Returns a sessionless launch url for an external tool.

Either the id or url must be provided.

Request Parameters:

  • id
    Optional, String

    The external id of the tool to launch.

  • url
    Optional, String

    The LTI launch url for the external tool.

  • assignment_id
    Optional, String

    The assignment id for an assignment launch.

  • launch_type
    Optional, String

    The type of launch to perform on the external tool.

API response field:

  • id

    The id for the external tool to be launched.

  • name

    The name of the external tool to be launched.

  • url

    The url to load to launch the external tool for the user.

Get a single external tool ExternalToolsController#show

GET /api/v1/courses/:course_id/external_tools/:external_tool_id

GET /api/v1/accounts/:account_id/external_tools/:external_tool_id

Returns the specified external tool.

API response field:

  • id

    The unique identifier for the tool

  • name

    The name of the tool

  • description

    A description of the tool

  • url

    The url to match links against

  • domain

    The domain to match links against

  • privacy_level

    What information to send to the external tool, "anonymous", "name_only", "public"

  • consumer_key

    The consumer key used by the tool (The associated shared secret is not returned)

  • created_at

    Timestamp of creation

  • updated_at

    Timestamp of last update

  • custom_fields

    Custom fields that will be sent to the tool consumer

  • account_navigation

    The configuration for account navigation links (see create API for values)

  • user_navigation

    The configuration for user navigation links (see create API for values)

  • course_navigation

    The configuration for course navigation links (see create API for values)

  • editor_button

    The configuration for a WYSIWYG editor button (see create API for values)

  • resource_selection

    The configuration for a resource selector in modules (see create API for values)

Example Response:

{
  "id":1,
  "name":"BLTI Example",
  "description":"This is for cool things"
  "url":"http://www.example.com/ims/lti",
  "domain":null,
  "privacy_level":anonymous
  "consumer_key":null,
  "created_at":"2037-07-21T13:29:31Z",
  "updated_at":"2037-07-28T19:38:31Z",
  "custom_fields":{"key":"value"},
  "account_navigation":{"url":"...", "text":"..."},
  "user_navigation":{"url":"...", "text":"..."},
  "course_navigation":{"url":"...", "text":"...", "visibility":"members", "default":true},
  "editor_button":{"url":"...", "selection_width":50, "selection_height":50, "icon_url":"..."},
  "resource_selection":{"url":"...", "selection_width":50, "selection_height":50}
}

Create an external tool ExternalToolsController#create

POST /api/v1/courses/:course_id/external_tools

POST /api/v1/accounts/:account_id/external_tools

Create an external tool in the specified course/account. The created tool will be returned, see the "show" endpoint for an example.

Request Parameters:

  • name
    String

    The name of the tool

  • privacy_level
    String, "anonymous"|"name_only"|"public"

    What information to send to the external tool.

  • consumer_key
    String

    The consumer key for the external tool

  • shared_secret
    String

    The shared secret with the external tool

  • description
    Optional, String

    A description of the tool

  • url
    Optional, String

    The url to match links against. Either "url" or "domain" should be set, not both.

  • domain
    Optional, String

    The domain to match links against. Either "url" or "domain" should be set, not both.

  • icon_url
    Optional, String

    The url of the icon to show for this tool

  • text
    Optional, String

    The default text to show for this tool

  • custom_fields
    Optional, String

    Custom fields that will be sent to the tool consumer, specified as custom_fields

  • account_navigation[url]
    Optional, String

    The url of the external tool for account navigation

  • account_navigation[enabled]
    Optional, Boolean

    Set this to enable this feature

  • account_navigation[text]
    Optional, String

    The text that will show on the left-tab in the account navigation

  • user_navigation[url]
    Optional, String

    The url of the external tool for user navigation

  • user_navigation[enabled]
    Optional, Boolean

    Set this to enable this feature

  • user_navigation[text]
    Optional, String

    The text that will show on the left-tab in the user navigation

  • course_navigation[url]
    Optional, String

    The url of the external tool for course navigation

  • course_navigation[enabled]
    Optional, Boolean

    Set this to enable this feature

  • course_navigation[text]
    Optional, String

    The text that will show on the left-tab in the course navigation

  • course_navigation[visibility]
    Optional, String, "admins"|"members"

    Who will see the navigation tab. "admins" for course admins, "members" for students, null for everyone

  • course_navigation[default]
    Optional, Boolean

    Whether the navigation option will show in the course by default or whether the teacher will have to explicitly enable it

  • editor_button[url]
    Optional, String

    The url of the external tool

  • editor_button[enabled]
    Optional, Boolean

    Set this to enable this feature

  • editor_button[icon_url]
    Optional, String

    The url of the icon to show in the WYSIWYG editor

  • editor_button[selection_width]
    Optional, String

    The width of the dialog the tool is launched in

  • editor_button[selection_height]
    Optional, String

    The height of the dialog the tool is launched in

  • resource_selection[url]
    Optional, String

    The url of the external tool

  • resource_selection[enabled]
    Optional, Boolean

    Set this to enable this feature

  • resource_selection[icon_url]
    Optional, String

    The url of the icon to show in the module external tool list

  • resource_selection[selection_width]
    Optional, String

    The width of the dialog the tool is launched in

  • resource_selection[selection_height]
    Optional, String

    The height of the dialog the tool is launched in

  • config_type
    Optional, String

    Configuration can be passed in as CC xml instead of using query parameters. If this value is "by_url" or "by_xml" then an xml configuration will be expected in either the "config_xml" or "config_url" parameter. Note that the name parameter overrides the tool name provided in the xml

  • config_xml
    Optional, String

    XML tool configuration, as specified in the CC xml specification. This is required if "config_type" is set to "by_xml"

  • config_url
    Optional, String

    URL where the server can retrieve an XML tool configuration, as specified in the CC xml specification. This is required if "config_type" is set to "by_url"

Example Request:

This would create a tool on this course with two custom fields and a course navigation tab
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools' \
     -H "Authorization: Bearer <token>" \ 
     -F 'name=LTI Example' \ 
     -F 'consumer_key=asdfg' \ 
     -F 'shared_secret=lkjh' \ 
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \ 
     -F 'custom_fields[key1]=value1' \ 
     -F 'custom_fields[key2]=value2' \ 
     -F 'course_navigation[text]=Course Materials' \
     -F 'course_navigation[default]=false'
     -F 'course_navigation[enabled]=true'

This would create a tool on the account with navigation for the user profile page
curl 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \ 
     -F 'name=LTI Example' \ 
     -F 'consumer_key=asdfg' \ 
     -F 'shared_secret=lkjh' \ 
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \ 
     -F 'user_navigation[url]=https://example.com/ims/lti/user_endpoint' \
     -F 'user_navigation[text]=Something Cool'
     -F 'user_navigation[enabled]=true'

This would create a tool on the account with configuration pulled from an external URL
curl 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \ 
     -F 'name=LTI Example' \ 
     -F 'consumer_key=asdfg' \ 
     -F 'shared_secret=lkjh' \ 
     -F 'config_type=by_url' \ 
     -F 'config_url=https://example.com/ims/lti/tool_config.xml'

Edit an external tool ExternalToolsController#update

PUT /api/v1/courses/:course_id/external_tools/:external_tool_id

PUT /api/v1/accounts/:account_id/external_tools/:external_tool_id

Update the specified external tool. Uses same parameters as create

Example Request:

This would update the specified keys on this external tool
curl -X PUT 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>" \ 
     -F 'name=Public Example' \ 
     -F 'privacy_level=public'

Delete an external tool ExternalToolsController#destroy

DELETE /api/v1/courses/:course_id/external_tools/:external_tool_id

DELETE /api/v1/accounts/:account_id/external_tools/:external_tool_id

Remove the specified external tool

Example Request:

This would delete the specified external tool
curl -X DELETE 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>"

List favorite courses FavoritesController#list_favorite_courses

GET /api/v1/users/self/favorites/courses

Retrieve the list of favorite courses for the current user. If the user has not chosen any favorites, then a selection of currently enrolled courses will be returned.

See the List courses API for details on accepted include[] parameters.

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses \ 
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a list of Courses

Add course to favorites FavoritesController#add_favorite_course

POST /api/v1/users/self/favorites/courses/:id

Add a course to the current user's favorites. If the course is already in the user's favorites, nothing happens.

Request Parameters:

  • id
    String

    The ID or SIS ID of the course to add. The current user must be registered in the course.

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses/1170 \ 
  -X POST \ 
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \ 
  -H 'Content-Length: 0'
Returns a Favorite

Remove course from favorites FavoritesController#remove_favorite_course

DELETE /api/v1/users/self/favorites/courses/:id

Remove a course from the current user's favorites.

Request Parameters:

  • id
    String

    the ID or SIS ID of the course to remove

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses/1170 \ 
  -X DELETE \ 
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Returns a Favorite

Reset course favorites FavoritesController#reset_course_favorites

DELETE /api/v1/users/self/favorites/courses

Reset the current user's course favorites to the default automatically generated list of enrolled courses

Example Request:

curl https://<canvas>/api/v1/users/self/favorites/courses \ 
  -X DELETE \ 
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

List features FeatureFlagsController#index

GET /api/v1/courses/:course_id/features

GET /api/v1/accounts/:account_id/features

GET /api/v1/users/:user_id/features

List all features that apply to a given Account, Course, or User.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features' \
  -H "Authorization: Bearer "
Returns a list of Features

List enabled features FeatureFlagsController#enabled_features

GET /api/v1/courses/:course_id/features/enabled

GET /api/v1/accounts/:account_id/features/enabled

GET /api/v1/users/:user_id/features/enabled

List all features that are enabled on a given Account, Course, or User. Only the feature names are returned.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features/enabled' \
  -H "Authorization: Bearer "

Example Response:

["fancy_wickets", "automatic_essay_grading", "telepathic_navigation"]

Get feature flag FeatureFlagsController#show

GET /api/v1/courses/:course_id/features/flags/:feature

GET /api/v1/accounts/:account_id/features/flags/:feature

GET /api/v1/users/:user_id/features/flags/:feature

Get the feature flag that applies to a given Account, Course, or User. The flag may be defined on the object, or it may be inherited from a parent account. You can look at the context_id and context_type of the returned object to determine which is the case. If these fields are missing, then the object is the global Canvas default.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer "
Returns a FeatureFlag

Set feature flag FeatureFlagsController#update

PUT /api/v1/courses/:course_id/features/flags/:feature

PUT /api/v1/accounts/:account_id/features/flags/:feature

PUT /api/v1/users/:user_id/features/flags/:feature

Set a feature flag for a given Account, Course, or User. This call will fail if a parent account sets a feature flag for the same feature in any state other than "allowed".

Request Parameters:

  • state
    Optional, String, "off"|"allowed"|"on"
    "off"

    The feature is not available for the course, user, or account and sub-accounts.

    "allowed"

    (valid only on accounts) The feature is off in the account, but may be enabled in sub-accounts and courses by setting a feature flag on the sub-account or course.

    "on"

    The feature is turned on unconditionally for the user, course, or account and sub-accounts.

  • locking_account_id
    Optional, Integer

    If set, this FeatureFlag may only be modified by someone with administrative rights in the specified account. The locking account must be above the target object in the account chain.

Example Request:

curl -X PUT 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer " \
  -F "state=on"
Returns a FeatureFlag

Remove feature flag FeatureFlagsController#delete

DELETE /api/v1/courses/:course_id/features/flags/:feature

DELETE /api/v1/accounts/:account_id/features/flags/:feature

DELETE /api/v1/users/:user_id/features/flags/:feature

Remove feature flag for a given Account, Course, or User. (Note that the flag must be defined on the Account, Course, or User directly.) The object will then inherit the feature flags from a higher account, if any exist. If this flag was 'on' or 'off', then lower-level account flags that were masked by this one will apply again.

Example Request:

curl -X DELETE 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer "
Returns a FeatureFlag

Get quota information FilesController#api_quota

GET /api/v1/courses/:course_id/files/quota

GET /api/v1/groups/:group_id/files/quota

GET /api/v1/users/:user_id/files/quota

Returns the total and used storage quota for the course, group, or user.

Example Request:

curl 'https://<canvas>/api/v1/courses/1/files/quota' \
      -H 'Authorization: Bearer <token>'

Example Response:

{ "quota": 524288000, "quota_used": 402653184 }

List files FilesController#api_index

GET /api/v1/courses/:course_id/files

GET /api/v1/folders/:id/files

Returns the paginated list of files for the folder or course.

Request Parameters:

  • content_types[]
    Optional, String

    Filter results by content-type. You can specify type/subtype pairs (e.g., 'image/jpeg'), or simply types (e.g., 'image', which will match 'image/gif', 'image/jpeg', etc.).

  • search_term
    Optional, String

    The partial name of the files to match and return.

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/files?content_types[]=image&content_types[]=text/plain \
      -H 'Authorization: Bearer <token>'
Returns a list of Files

Get file FilesController#api_show

GET /api/v1/files/:id

Returns the standard attachment json object

Example Request:

curl 'https://<canvas>/api/v1/files/<file_id>' \
      -H 'Authorization: Bearer <token>'
Returns a File

Update file FilesController#api_update

PUT /api/v1/files/:id

Update some settings on the specified file

Request Parameters:

  • name
    String

    The new display name of the file

  • parent_folder_id
    String

    The id of the folder to move this file into. The new folder must be in the same context as the original parent folder. If the file is in a context without folders this does not apply.

  • lock_at
    DateTime

    The datetime to lock the file at

  • unlock_at
    DateTime

    The datetime to unlock the file at

  • locked
    Boolean

    Flag the file as locked

  • hidden
    Boolean

    Flag the file as hidden

Example Request:

curl -XPUT 'https://<canvas>/api/v1/files/<file_id>' \ 
     -F 'name=<new_name>' \ 
     -F 'locked=true' \ 
     -H 'Authorization: Bearer <token>'
Returns a File

Delete file FilesController#destroy

DELETE /api/v1/files/:id

Remove the specified file

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

List folders FoldersController#api_index

GET /api/v1/folders/:id/folders

Returns the paginated list of folders in the folder.

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/folders' \ 
     -H 'Authorization: Bearer <token>'
Returns a list of Folders

Get folder FoldersController#show

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

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

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

GET /api/v1/folders/:id

Returns the details for a folder

You can get the root folder from a context by using 'root' as the :id. For example, you could get the root folder for a course like:

Example Request:

curl 'https://<canvas>/api/v1/courses/1337/folders/root' \ 
     -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/folders/<folder_id>' \ 
     -H 'Authorization: Bearer <token>'
Returns a Folder

Update folder FoldersController#update

PUT /api/v1/folders/:id

Updates a folder

Request Parameters:

  • name
    String

    The new name of the folder

  • parent_folder_id
    String

    The id of the folder to move this folder into. The new folder must be in the same context as the original parent folder.

  • lock_at
    DateTime

    The datetime to lock the folder at

  • unlock_at
    DateTime

    The datetime to unlock the folder at

  • locked
    Boolean

    Flag the folder as locked

  • hidden
    Boolean

    Flag the folder as hidden

  • position
    Integer

    Set an explicit sort position for the folder

Example Request:

curl -XPUT 'https://<canvas>/api/v1/folders/<folder_id>' \ 
     -F 'name=<new_name>' \ 
     -F 'locked=true' \ 
     -H 'Authorization: Bearer <token>'
Returns a Folder

Create folder FoldersController#create

POST /api/v1/courses/:course_id/folders

POST /api/v1/users/:user_id/folders

POST /api/v1/groups/:group_id/folders

POST /api/v1/folders/:folder_id/folders

Creates a folder in the specified context

Request Parameters:

  • name
    String

    The name of the folder

  • parent_folder_id
    String

    The id of the folder to store the file in. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used.

  • parent_folder_path
    String

    The path of the folder to store the new folder in. The path separator is the forward slash `/`, never a back slash. The parent folder will be created if it does not already exist. This parameter only applies to new folders in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used.

  • lock_at
    DateTime

    The datetime to lock the folder at

  • unlock_at
    DateTime

    The datetime to unlock the folder at

  • locked
    Boolean

    Flag the folder as locked

  • hidden
    Boolean

    Flag the folder as hidden

  • position
    Integer

    Set an explicit sort position for the folder

Example Request:

curl 'https://<canvas>/api/v1/folders/<folder_id>/folders' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'

curl 'https://<canvas>/api/v1/courses/<course_id>/folders' \
     -F 'name=<new_name>' \
     -F 'locked=true' \
     -H 'Authorization: Bearer <token>'
Returns a Folder

Delete folder FoldersController#api_destroy

DELETE /api/v1/folders/:id

Remove the specified folder. You can only delete empty folders unless you set the 'force' flag

Request Parameters:

  • force
    Boolean

    Set to 'true' to allow deleting a non-empty folder

Example Request:

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

Upload a file FoldersController#create_file

POST /api/v1/folders/:folder_id/files

Upload a file to a folder.

This API endpoint is the first step in uploading a file. See the File Upload Documentation for details on the file upload workflow.

Only those with the "Manage Files" permission on a course or group can upload files to a folder in that course or group.

Query by assignment. GradeChangeAuditApiController#for_assignment

GET /api/v1/audit/grade_change/assignments/:assignment_id

List grade change events for a given assignment.

Request Parameters:

  • start_time
    Optional, DateTime

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

  • end_time
    Optional, Datetime

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

Returns a list of GradeChangeEvents

Query by course. GradeChangeAuditApiController#for_course

GET /api/v1/audit/grade_change/courses/:course_id

List grade change events for a given course.

Request Parameters:

  • start_time
    Optional, DateTime

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

  • end_time
    Optional, Datetime

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

Returns a list of GradeChangeEvents

Query by student. GradeChangeAuditApiController#for_student

GET /api/v1/audit/grade_change/students/:student_id

List grade change events for a given student.

Request Parameters:

  • start_time
    Optional, DateTime

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

  • end_time
    Optional, Datetime

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

Returns a list of GradeChangeEvents

Query by grader. GradeChangeAuditApiController#for_grader

GET /api/v1/audit/grade_change/graders/:grader_id

List grade change events for a given grader.

Request Parameters:

  • start_time
    Optional, DateTime

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

  • end_time
    Optional, Datetime

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

Returns a list of GradeChangeEvents

Days in gradebook history for this course GradebookHistoryApiController#days

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

GET /api/v1/courses/:course_id/gradebook_history/days

Returns a map of dates to grader/assignment groups

Request Parameters:

  • course_id
    Integer

    The id of the contextual course for this API call

Returns a list of Days

Details for a given date in gradebook history for this course GradebookHistoryApiController#day_details

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

GET /api/v1/courses/:course_id/gradebook_history/:date

Returns the graders who worked on this day, along with the assignments they worked on. More details can be obtained by selecting a grader and assignment and calling the 'submissions' api endpoint for a given date.

Request Parameters:

  • course_id
    Integer

    The id of the contextual course for this API call

  • date
    String

    The date for which you would like to see detailed information

Returns a list of Graders

Lists submissions GradebookHistoryApiController#submissions

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

GET /api/v1/courses/:course_id/gradebook_history/:date/graders/:grader_id/assignments/:assignment_id/submissions

Gives a nested list of submission versions

Request Parameters:

  • course_id
    Integer

    The id of the contextual course for this API call

  • date
    String

    The date for which you would like to see submissions

  • grader_id
    Integer

    The ID of the grader for which you want to see submissions

  • assignment_id
    Integer

    The ID of the assignment for which you want to see submissions

Returns a list of SubmissionHistories

List uncollated submission versions GradebookHistoryApiController#feed

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

GET /api/v1/courses/:course_id/gradebook_history/feed

Gives a paginated, uncollated list of submission versions for all matching submissions in the context. This SubmissionVersion objects will not include the new_grade or previous_grade keys, only the grade; same for graded_at and grader.

Request Parameters:

  • course_id
    Integer

    The id of the contextual course for this API call

  • assignment_id
    Optional, Integer

    The ID of the assignment for which you want to see submissions. If absent, versions of submissions from any assignment in the course are included.

  • user_id
    Optional, Integer

    The ID of the user for which you want to see submissions. If absent, versions of submissions from any user in the course are included.

  • ascending
    Optional, Boolean

    Returns submission versions in ascending date order (oldest first). If absent, returns submission versions in descending date order (newest first).

Returns a list of SubmissionVersions

Create a new grading standard GradingStandardsApiController#create

POST /api/v1/accounts/:account_id/grading_standards

POST /api/v1/courses/:course_id/grading_standards

Create a new grading standard

If grading_scheme_entry arguments are omitted, then a default grading scheme will be set. The default scheme is as follows:

"A" : 94,
"A-" : 90,
"B+" : 87,
"B" : 84,
"B-" : 80,
"C+" : 77,
"C" : 74,
"C-" : 70,
"D+" : 67,
"D" : 64,
"D-" : 61,
"F" : 0,

Request Parameters:

  • title
    String

    The title for the Grading Standard.

  • grading_scheme_entry[][name]
    String

    The name for an entry value within a GradingStandard that describes the range of the value e.g. A-

  • grading_scheme_entry[][value]
    Integer

    The value for the name of the entry within a GradingStandard. The entry represents the lower bound of the range for the entry. This range includes the value up to the next entry in the GradingStandard, or 100 if there is no upper bound. The lowest value will have a lower bound range of 0. e.g. 93

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/grading_standards \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'title=New standard name' \
  -d 'grading_scheme_entry[][name]=A'
  -d 'grading_scheme_entry[][value]=90'
  -d 'grading_scheme_entry[][name]=B'
  -d 'grading_scheme_entry[][value]=80'

Example Response:

{
  "title": "New standard name",
  "id": 1,
  "context_id": 1,
  "context_type": "Course",
  "grading_scheme": [
    {"name": "A", "value": 0.9},
    {"name": "B", "value": 0.8}
  ]
}
Returns a GradingStandard

List group categories for a context GroupCategoriesController#index

GET /api/v1/accounts/:account_id/group_categories

GET /api/v1/courses/:course_id/group_categories

Returns a list of group categories in a context

Example Request:

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

Get a single group category GroupCategoriesController#show

GET /api/v1/group_categories/:group_category_id

Returns the data for a single group category, or a 401 if the caller doesn't have the rights to see it.

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
     -H 'Authorization: Bearer <token>'
Returns a GroupCategory

Create a Group Category GroupCategoriesController#create

POST /api/v1/accounts/:account_id/group_categories

POST /api/v1/courses/:course_id/group_categories

Create a new group category

Request Parameters:

  • name
    String

    Name of the group category

  • self_signup
    Optional, "enabled"|"restricted"

    Allow students to sign up for a group themselves (Course Only). valid values are:

    "enabled"

    allows students to self sign up for any group in course

    "restricted"

    allows students to self sign up only for groups in the same section null disallows self sign up

  • group_limit
    Optional

    Limit the maximum number of users in each group (Course Only). Requires self signup.

  • create_group_count
    Optional

    Create this number of groups (Course Only).

  • split_group_count
    Optional

    (Deprecated)

    Create this number of groups, and evenly distribute students among them. not allowed with "enable_self_signup". because the group assignment happens synchronously, it's recommended that you instead use the assign_unassigned_members endpoint. (Course Only)

Example Request:

curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \ 
    -F 'name=Project Groups' \ 
    -H 'Authorization: Bearer <token>'
Returns a GroupCategory

Update a Group Category GroupCategoriesController#update

PUT /api/v1/group_categories/:group_category_id

Modifies an existing group category.

Request Parameters:

  • name
    String

    Name of the group category

  • self_signup
    Optional, "enabled"|"restricted"

    Allow students to sign up for a group themselves (Course Only). Valid values are:

    "enabled"

    allows students to self sign up for any group in course

    "restricted"

    allows students to self sign up only for groups in the same section null disallows self sign up

  • group_limit
    Optional

    Limit the maximum number of users in each group (Course Only). Requires self signup.

  • create_group_count
    Optional

    Create this number of groups (Course Only).

  • split_group_count
    Optional

    (Deprecated)

    Create this number of groups, and evenly distribute students among them. not allowed with "enable_self_signup". because the group assignment happens synchronously, it's recommended that you instead use the assign_unassigned_members endpoint. (Course Only)

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
    -X PUT \ 
    -F 'name=Project Groups' \ 
    -H 'Authorization: Bearer <token>'
Returns a GroupCategory

Delete a Group Category GroupCategoriesController#destroy

DELETE /api/v1/group_categories/:group_category_id

Deletes a group category and all groups under it. Protected group categories can not be deleted, i.e. "communities", "student_organized", and "imported".

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_category_id> \
      -X DELETE \ 
      -H 'Authorization: Bearer <token>'

List groups in group category GroupCategoriesController#groups

GET /api/v1/group_categories/:group_category_id/groups

Returns a list of groups in a group category

Example Request:

curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \ 
     -H 'Authorization: Bearer <token>'
Returns a list of Groups

List users in group category GroupCategoriesController#users

GET /api/v1/group_categories/:group_category_id/users

Returns a list of users in the group category.

Request Parameters:

  • search_term
    Optional, String

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

  • unassigned
    Optional, Boolean

    Set this value to true if you wish only to search unassigned users in the group category.

Example Request:

curl https://<canvas>/api/v1/group_categories/1/users \
     -H 'Authorization: Bearer <token>'
Returns a list of Users

Assign unassigned members GroupCategoriesController#assign_unassigned_members

POST /api/v1/group_categories/:group_category_id/assign_unassigned_members

Assign all unassigned members as evenly as possible among the existing student groups.

Request Parameters:

  • sync
    Optional, Boolean

    The assigning is done asynchronously by default. If you would like to override this and have the assigning done synchronously, set this value to true.

Example Request:

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

Example Response:

# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "GroupCategory",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "assign_unassigned_members",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}

# New Group Memberships (when sync = true)
[
  {
    "id": 65,
    "new_members": [
      {
        "user_id": 2,
        "name": "Sam",
        "display_name": "Sam",
        "sections": [
          {
            "section_id": 1,
            "section_code": "Section 1"
          }
        ]
      },
      {
        "user_id": 3,
        "name": "Sue",
        "display_name": "Sue",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      }
    ]
  },
  {
    "id": 66,
    "new_members": [
      {
        "user_id": 5,
        "name": "Joe",
        "display_name": "Joe",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      },
      {
        "user_id": 11,
        "name": "Cecil",
        "display_name": "Cecil",
        "sections": [
          {
            "section_id": 3,
            "section_code": "Section 3"
          }
        ]
      }
    ]
  }
]

List your groups GroupsController#index

GET /api/v1/users/self/groups

Returns a list of active groups for the current user.

Request Parameters:

  • context_type
    Optional, String, "Account"|"Course"

    Only include groups that are in this type of context.

Example Request:

curl https://<canvas>/api/v1/users/self/groups?context_type=Account \ 
     -H 'Authorization: Bearer <token>'
Returns a list of Groups

List the groups available in a context. GroupsController#context_index

GET /api/v1/accounts/:account_id/groups

GET /api/v1/courses/:course_id/groups

Returns the list of active groups in the given context that are visible to user.

Example Request:

curl https://<canvas>/api/v1/courses/1/groups \ 
     -H 'Authorization: Bearer <token>'
Returns a list of Groups

Get a single group GroupsController#show

GET /api/v1/groups/:group_id

Returns the data for a single group, or a 401 if the caller doesn't have the rights to see it.

Request Parameters:

  • include[]
    String, "permissions"
    • "permissions": Include permissions the current user has for the group.

Example Request:

curl https://<canvas>/api/v1/groups/<group_id> \ 
     -H 'Authorization: Bearer <token>'
Returns a Group

Create a group GroupsController#create

POST /api/v1/groups

POST /api/v1/group_categories/:group_category_id/groups

Creates a new group. Groups created using the "/api/v1/groups/" endpoint will be community groups.

Request Parameters:

  • name
    String

    The name of the group

  • description
    String

    A description of the group

  • is_public
    Boolean

    whether the group is public (applies only to community groups)

  • join_level
    String, "parent_context_auto_join"|"parent_context_request"|"invitation_only"
  • storage_quota_mb
    Integer

    The allowed file storage for the group, in megabytes. This parameter is ignored if the caller does not have the manage_storage_quotas permission.

Example Request:

curl https://<canvas>/api/v1/groups \ 
     -F 'name=Math Teachers' \ 
     -F 'description=A place to gather resources for our classes.' \ 
     -F 'is_public=true' \ 
     -F 'join_level=parent_context_auto_join' \ 
     -H 'Authorization: Bearer <token>'
Returns a Group

Edit a group GroupsController#update

PUT /api/v1/groups/:group_id

Modifies an existing group. Note that to set an avatar image for the group, you must first upload the image file to the group, and the use the id in the response as the argument to this function. See the File Upload Documentation for details on the file upload workflow.

Request Parameters:

  • name
    String

    The name of the group

  • description
    String

    A description of the group

  • is_public
    Boolean

    Whether the group is public (applies only to community groups). Currently you cannot set a group back to private once it has been made public.

  • join_level
    String, "parent_context_auto_join"|"parent_context_request"|"invitation_only"
  • avatar_id
    Integer

    The id of the attachment previously uploaded to the group that you would like to use as the avatar image for this group.

  • storage_quota_mb
    Integer

    The allowed file storage for the group, in megabytes. This parameter is ignored if the caller does not have the manage_storage_quotas permission.

Example Request:

curl https://<canvas>/api/v1/groups/<group_id> \ 
     -X PUT \ 
     -F 'name=Algebra Teachers' \ 
     -F 'join_level=parent_context_request' \ 
     -H 'Authorization: Bearer <token>'
Returns a Group

Delete a group GroupsController#destroy

DELETE /api/v1/groups/:group_id

Deletes a group and removes all members.

Example Request:

curl https://<canvas>/api/v1/groups/<group_id> \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'
Returns a Group

Invite others to a group GroupsController#invite

POST /api/v1/groups/:group_id/invite

Sends an invitation to all supplied email addresses which will allow the receivers to join the group.

Request Parameters:

  • invitees[]
    String

    An array of email addresses to be sent invitations.

Example Request:

curl https://<canvas>/api/v1/groups/<group_id>/invite \ 
     -F 'invitees[]=leonard@example.com&invitees[]=sheldon@example.com' \ 
     -H 'Authorization: Bearer <token>'

List group's users GroupsController#users

GET /api/v1/groups/:group_id/users

Returns a list of users in the group.

Request Parameters:

  • search_term
    Optional, String

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

Example Request:

curl https://<canvas>/api/v1/groups/1/users \
     -H 'Authorization: Bearer <token>'
Returns a list of Users

Upload a file GroupsController#create_file

POST /api/v1/groups/:group_id/files

Upload a file to the group.

This API endpoint is the first step in uploading a file to a group. See the File Upload Documentation for details on the file upload workflow.

Only those with the "Manage Files" permission on a group can upload files to the group. By default, this is anybody participating in the group, or any admin over the group.

Preview processed html GroupsController#preview_html

POST /api/v1/groups/:group_id/preview_html

Preview html content processed for this group

Request Parameters:

  • html
    String

    The html content to process

Example Request:

curl https://<canvas>/api/v1/groups/<group_id>/preview_html \
     -F 'html=<p><badhtml></badhtml>processed html</p>' \
     -H 'Authorization: Bearer <token>'

Example Response:

{
  "html": "<p>processed html</p>"
}

Group activity stream GroupsController#activity_stream

GET /api/v1/groups/:group_id/activity_stream

Returns the current user's group-specific activity stream, paginated.

For full documentation, see the API documentation for the user activity stream, in the user api.

Group activity stream summary GroupsController#activity_stream_summary

GET /api/v1/groups/:group_id/activity_stream/summary

Returns a summary of the current user's group-specific activity stream.

For full documentation, see the API documentation for the user activity stream summary, in the user api.

List group memberships GroupMembershipsController#index

GET /api/v1/groups/:group_id/memberships

GET /api/v1/groups/:group_id/users

List the members of a group.

Request Parameters:

  • filter_states[]
    Optional, String, "accepted"|"invited"|"requested"

    Only list memberships with the given workflow_states. By default it will return all memberships.

Example Request:

curl https://<canvas>/api/v1/groups/<group_id>/memberships \ 
     -F 'filter_states[]=invited&filter_states[]=requested' \ 
     -H 'Authorization: Bearer <token>'
Returns a list of GroupMemberships

Create a membership GroupMembershipsController#create

POST /api/v1/groups/:group_id/memberships

Join, or request to join, a group, depending on the join_level of the group. If the membership or join request already exists, then it is simply returned

Request Parameters:

  • user_id
    String

Example Request:

curl https://<canvas>/api/v1/groups/<group_id>/memberships \ 
     -F 'user_id=self'
     -H 'Authorization: Bearer <token>'
Returns a GroupMembership

Update a membership GroupMembershipsController#update

PUT /api/v1/groups/:group_id/memberships/:membership_id

PUT /api/v1/groups/:group_id/users/:user_id

Accept a membership request, or add/remove moderator rights.

Request Parameters:

  • workflow_state
    Optional, String, "accepted"

    Currently, the only allowed value is "accepted"

  • moderator

Example Request:

curl https://<canvas>/api/v1/groups/<group_id>/memberships/<membership_id> \ 
     -F 'moderator=true'
     -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/groups/<group_id>/users/<user_id> \
     -F 'moderator=true'
     -H 'Authorization: Bearer <token>'
Returns a GroupMembership

Leave a group GroupMembershipsController#destroy

DELETE /api/v1/groups/:group_id/memberships/:membership_id

DELETE /api/v1/groups/:group_id/users/:user_id

Leave a group if you are allowed to leave (some groups, such as sets of course groups created by teachers, cannot be left). You may also use 'self' in place of a membership_id.

Example Request:

curl https://<canvas>/api/v1/groups/<group_id>/memberships/<membership_id> \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/groups/<group_id>/users/<user_id> \
     -X DELETE \
     -H 'Authorization: Bearer <token>'

List user logins PseudonymsController#index

GET /api/v1/accounts/:account_id/logins

GET /api/v1/users/:user_id/logins

Given a user ID, return that user's logins for the given account.

Request Parameters:

  • user[id]
    String

    The ID of the user to search on.

API response field:

  • account_id

    The ID of the login's account.

  • id

    The unique, numeric ID for the login.

  • sis_user_id

    The login's unique SIS id.

  • unique_id

    The unique ID for the login.

  • user_id

    The unique ID of the login's user.

Example Response:

[
   { "account_id": 1, "id" 2, "sis_user_id": null, "unique_id": "belieber@example.com", "user_id": 2 }
]

Create a user login PseudonymsController#create

POST /api/v1/accounts/:account_id/logins

Create a new login for an existing user in the given account.

Request Parameters:

  • user[id]
    String

    The ID of the user to create the login for.

  • login[unique_id]
    String

    The unique ID for the new login.

  • login[password]
    String

    The new login's password.

  • login[sis_user_id]
    String

    SIS ID for the login. To set this parameter, the caller must be able to manage SIS permissions on the account.

Edit a user login PseudonymsController#update

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

Update an existing login for a user in the given account.

Request Parameters:

  • login[unique_id]
    String

    The new unique ID for the login.

  • login[password]
    String

    The new password for the login. Can only be set by an admin user if admins are allowed to change passwords for the account.

  • login[sis_user_id]
    String

    SIS ID for the login. To set this parameter, the caller must be able to manage SIS permissions on the account.

Delete a user login PseudonymsController#destroy

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

Delete an existing login.

Example Request:

curl https://<canvas>/api/v1/users/:user_id/logins/:login_id \ 
  -H "Authorization: Bearer <ACCESS-TOKEN>" \ 
  -X DELETE

Example Response:

{
  "unique_id": "bieber@example.com",
  "sis_user_id": null,
  "account_id": 1,
  "id": 12345,
  "user_id": 2
}

List modules ContextModulesApiController#index

GET /api/v1/courses/:course_id/modules

List the modules in a course

Request Parameters:

  • include[]
    String, "items"|"content_details"
    • "items": Return module items inline if possible. This parameter suggests that Canvas return module items directly in the Module object JSON, to avoid having to make separate API requests for each module when enumerating modules and items. Canvas is free to omit 'items' for any particular module if it deems them too numerous to return inline. Callers must be prepared to use the List Module Items API if items are not returned.

    • "content_details": Requires include. Returns additional details with module items specific to their associated content items.

  • search_term
    Optional, String

    The partial name of the modules (and module items, if include is specified) to match and return.

  • student_id
    Optional

    Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules
Returns a list of Modules

Show module ContextModulesApiController#show

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

Get information about a single module

Request Parameters:

  • include[]
    String, "items"|"content_details"
    • "items": Return module items inline if possible. This parameter suggests that Canvas return module items directly in the Module object JSON, to avoid having to make separate API requests for each module when enumerating modules and items. Canvas is free to omit 'items' for any particular module if it deems them too numerous to return inline. Callers must be prepared to use the List Module Items API if items are not returned.

    • "content_details": Requires include. Returns additional details with module items specific to their associated content items.

  • student_id
    Optional

    Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123
Returns a Module

Create a module ContextModulesApiController#create

POST /api/v1/courses/:course_id/modules

Create and return a new module

Request Parameters:

  • module[name]
    String

    The name of the module

  • module[unlock_at]
    Optional, DateTime

    The date the module will unlock

  • module[position]
    Optional, Integer

    The position of this module in the course (1-based)

  • module[require_sequential_progress]
    Optional, Boolean

    Whether module items must be unlocked in order

  • module[prerequisite_module_ids][]
    Optional, String

    IDs of Modules that must be completed before this one is unlocked. Prerequisite modules must precede this module (i.e. have a lower position value), otherwise they will be ignored

  • module[publish_final_grade]
    Optional, Boolean

    Whether to publish the student's final grade for the course upon completion of this module.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'module[name]=module' \
  -d 'module[position]=2' \
  -d 'module[prerequisite_module_ids][]=121' \
  -d 'module[prerequisite_module_ids][]=122'
Returns a Module

Update a module ContextModulesApiController#update

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

Update and return an existing module

Request Parameters:

  • module[name]
    Optional, String

    The name of the module

  • module[unlock_at]
    Optional, DateTime

    The date the module will unlock

  • module[position]
    Optional, Integer

    The position of the module in the course (1-based)

  • module[require_sequential_progress]
    Optional, Boolean

    Whether module items must be unlocked in order

  • module[prerequisite_module_ids][]
    Optional, String

    IDs of Modules that must be completed before this one is unlocked Prerequisite modules must precede this module (i.e. have a lower position value), otherwise they will be ignored

  • module[publish_final_grade]
    Optional, Boolean

    Whether to publish the student's final grade for the course upon completion of this module.

  • module[published]
    Optional, Boolean

    Whether the module is published and visible to students

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'module[name]=module' \
  -d 'module[position]=2' \
  -d 'module[prerequisite_module_ids][]=121' \
  -d 'module[prerequisite_module_ids][]=122'
Returns a Module

Delete module ContextModulesApiController#destroy

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

Delete a module

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id> \
  -X Delete \
  -H 'Authorization: Bearer <token>'
Returns a Module

List module items ContextModuleItemsApiController#index

GET /api/v1/courses/:course_id/modules/:module_id/items

List the items in a module

Request Parameters:

  • include[]
    String, "content_details"

    If included, will return additional details specific to the content associated with each item. Refer to the Module Item specification for more details.

  • search_term
    Optional, String

    The partial title of the items to match and return.

  • student_id
    Optional

    Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123/items
Returns a list of ModuleItems

Show module item ContextModuleItemsApiController#show

GET /api/v1/courses/:course_id/modules/:module_id/items/:id

Get information about a single module item

Request Parameters:

  • include[]
    String, "content_details"

    If included, will return additional details specific to the content associated with this item. Refer to the Module Item specification for more details.

  • student_id
    Optional

    Returns module completion information for the student with this id.

Example Request:

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123/items/768
Returns a ModuleItem

Create a module item ContextModuleItemsApiController#create

POST /api/v1/courses/:course_id/modules/:module_id/items

Create and return a new module item

Request Parameters:

  • module_item[title]
    Optional, String

    The name of the module item and associated content

  • module_item[type]
    String, "File"|"Page"|"Discussion"|"Assignment"|"Quiz"|"SubHeader"|"ExternalUrl"|"ExternalTool"

    The type of content linked to the item

  • module_item[content_id]
    String

    The id of the content to link to the module item. Required, except for 'ExternalUrl', 'Page', and 'SubHeader' types.

  • module_item[position]
    Optional, Integer

    The position of this item in the module (1-based).

  • module_item[indent]
    Optional, Integer

    0-based indent level; module items may be indented to show a hierarchy

  • module_item[page_url]
    String

    Suffix for the linked wiki page (e.g. 'front-page'). Required for 'Page' type.

  • module_item[external_url]
    String

    External url that the item points to. [Required for 'ExternalUrl' and 'ExternalTool' types.

  • module_item[new_tab]
    Optional, Boolean

    Whether the external tool opens in a new tab. Only applies to 'ExternalTool' type.

  • module_item[completion_requirement][type]
    Optional, String, "must_view"|"must_contribute"|"must_submit"

    Completion requirement for this module item. "must_view": Applies to all item types "must_contribute": Only applies to "Assignment", "Discussion", and "Page" types "must_submit", "min_score": Only apply to "Assignment" and "Quiz" types Inapplicable types will be ignored

  • module_item[completion_requirement][min_score]
    Integer

    Minimum score required to complete. Required for completion_requirement type 'min_score'.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -d 'module_item[title]=module item' \
  -d 'module_item[type]=ExternalTool' \
  -d 'module_item[content_id]=10' \
  -d 'module_item[position]=2' \
  -d 'module_item[indent]=1' \
  -d 'module_item[new_tab]=true'
Returns a ModuleItem

Update a module item ContextModuleItemsApiController#update

PUT /api/v1/courses/:course_id/modules/:module_id/items/:id

Update and return an existing module item

Request Parameters:

  • module_item[title]
    Optional, String

    The name of the module item

  • module_item[position]
    Optional, Integer

    The position of this item in the module (1-based)

  • module_item[indent]
    Optional, Integer

    0-based indent level; module items may be indented to show a hierarchy

  • module_item[external_url]
    Optional, String

    External url that the item points to. Only applies to 'ExternalUrl' type.

  • module_item[new_tab]
    Optional, Boolean

    Whether the external tool opens in a new tab. Only applies to 'ExternalTool' type.

  • module_item[completion_requirement][type]
    Optional, "must_view"|"must_contribute"|"must_submit"

    Completion requirement for this module item. "must_view": Applies to all item types "must_contribute": Only applies to "Assignment", "Discussion", and "Page" types "must_submit", "min_score": Only apply to "Assignment" and "Quiz" types Inapplicable types will be ignored

  • module_item[completion_requirement][min_score]
    Integer

    Minimum score required to complete, Required for completion_requirement type 'min_score'.

  • module_item[published]
    Optional, Boolean

    Whether the module item is published and visible to students.

  • module_item[module_id]
    Optional, String

    Move this item to another module by specifying the target module id here. The target module must be in the same course.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'module_item[content_id]=10' \
  -d 'module_item[position]=2' \
  -d 'module_item[indent]=1' \
  -d 'module_item[new_tab]=true'
Returns a ModuleItem

Delete module item ContextModuleItemsApiController#destroy

DELETE /api/v1/courses/:course_id/modules/:module_id/items/:id

Delete a module item

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id> \
  -X Delete \
  -H 'Authorization: Bearer <token>'
Returns a ModuleItem

Get module item sequence ContextModuleItemsApiController#item_sequence

GET /api/v1/courses/:course_id/module_item_sequence

Given an asset in a course, find the ModuleItem it belongs to, and also the previous and next Module Items in the course sequence.

Request Parameters:

  • asset_type
    String, "ModuleItem"|"File"|"Page"|"Discussion"|"Assignment"|"Quiz"|"ExternalTool"

    The type of asset to find module sequence information for. Use the ModuleItem if it is known (e.g., the user navigated from a module item), since this will avoid ambiguity if the asset appears more than once in the module sequence.

  • asset_id
    Integer

    The id of the asset (or the url in the case of a Page)

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/module_item_sequence?asset_type=Assignment&asset_id=123 \
  -H 'Authorization: Bearer <token>'
Returns a ModuleItemSequence

List preferences NotificationPreferencesController#index

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

GET /api/v1/users/:user_id/communication_channels/:type/:address/notification_preferences

Fetch all preferences for the given communication channel

Returns a list of NotificationPreferences

Get a preference NotificationPreferencesController#show

GET /api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preferences/:notification

GET /api/v1/users/:user_id/communication_channels/:type/:address/notification_preferences/:notification

Fetch the preference for the given notification for the given communicaiton channel

Returns a NotificationPreference

Update a preference NotificationPreferencesController#update

PUT /api/v1/users/self/communication_channels/:communication_channel_id/notification_preferences/:notification

PUT /api/v1/users/self/communication_channels/:type/:address/notification_preferences/:notification

Change the preference for a single notification for a single communication channel

Request Parameters:

  • notification_preferences[frequency]

    The desired frequency for this notification

Update multiple preferences NotificationPreferencesController#update_all

PUT /api/v1/users/self/communication_channels/:communication_channel_id/notification_preferences

PUT /api/v1/users/self/communication_channels/:type/:address/notification_preferences

Change the preferences for multiple notifications for a single communication channel at once

Request Parameters:

  • notification_preferences[<X>][frequency]

    The desired frequency for <X> notification

Redirect to root outcome group for context OutcomeGroupsApiController#redirect

GET /api/v1/global/root_outcome_group

GET /api/v1/accounts/:account_id/root_outcome_group

GET /api/v1/courses/:course_id/root_outcome_group

Convenience redirect to find the root outcome group for a particular context. Will redirect to the appropriate outcome group's URL.

Get all outcome groups for context OutcomeGroupsApiController#index

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

GET /api/v1/accounts/:account_id/outcome_groups

GET /api/v1/courses/:course_id/outcome_groups

Get all outcome links for context OutcomeGroupsApiController#link_index

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

GET /api/v1/accounts/:account_id/outcome_group_links

GET /api/v1/courses/:course_id/outcome_group_links

Show an outcome group OutcomeGroupsApiController#show

GET /api/v1/global/outcome_groups/:id

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

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

Update an outcome group OutcomeGroupsApiController#update

PUT /api/v1/global/outcome_groups/:id

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

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

Modify an existing outcome group. Fields not provided are left as is; unrecognized fields are ignored.

When changing the parent outcome group, the new parent group must belong to the same context as this outcome group, and must not be a descendant of this outcome group (i.e. no cycles allowed).

Request Parameters:

  • title
    Optional, String

    The new outcome group title.

  • description
    Optional, String

    The new outcome group description.

  • vendor_guid
    Optional, String

    A custom GUID for the learning standard.

  • parent_outcome_group_id
    Optional, Integer

    The id of the new parent outcome group.

Example Request:

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \
     -X PUT \ 
     -F 'title=Outcome Group Title' \ 
     -F 'description=Outcome group description' \
     -F 'vendor_guid=customid9000' \
     -F 'parent_outcome_group_id=1' \ 
     -H "Authorization: Bearer <token>"

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \
     -X PUT \ 
     --data-binary '{
           "title": "Outcome Group Title",
           "description": "Outcome group description",
           "vendor_guid": "customid9000",
           "parent_outcome_group_id": 1
         }' \ 
     -H "Content-Type: application/json" \ 
     -H "Authorization: Bearer <token>"
Returns a OutcomeGroup

Delete an outcome group OutcomeGroupsApiController#destroy

DELETE /api/v1/global/outcome_groups/:id

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

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

Deleting an outcome group deletes descendant outcome groups and outcome links. The linked outcomes themselves are only deleted if all links to the outcome were deleted.

Aligned outcomes cannot be deleted; as such, if all remaining links to an aligned outcome are included in this group's descendants, the group deletion will fail.

Example Request:

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \
     -X DELETE \ 
     -H "Authorization: Bearer <token>"
Returns a OutcomeGroup

List linked outcomes OutcomeGroupsApiController#outcomes

GET /api/v1/global/outcome_groups/:id/outcomes

GET /api/v1/accounts/:account_id/outcome_groups/:id/outcomes

GET /api/v1/courses/:course_id/outcome_groups/:id/outcomes

List the immediate OutcomeLink children of the outcome group. Paginated.

Returns a list of OutcomeLinks

Create/link an outcome OutcomeGroupsApiController#link

POST /api/v1/global/outcome_groups/:id/outcomes

PUT /api/v1/global/outcome_groups/:id/outcomes/:outcome_id

POST /api/v1/accounts/:account_id/outcome_groups/:id/outcomes

PUT /api/v1/accounts/:account_id/outcome_groups/:id/outcomes/:outcome_id

POST /api/v1/courses/:course_id/outcome_groups/:id/outcomes

PUT /api/v1/courses/:course_id/outcome_groups/:id/outcomes/:outcome_id

Link an outcome into the outcome group. The outcome to link can either be specified by a PUT to the link URL for a specific outcome (the outcome_id in the PUT URLs) or by supplying the information for a new outcome (title, description, ratings, mastery_points) in a POST to the collection.

If linking an existing outcome, the outcome_id must identify an outcome available to this context; i.e. an outcome owned by this group's context, an outcome owned by an associated account, or a global outcome. With outcome_id present, any other parameters are ignored.

If defining a new outcome, the outcome is created in the outcome group's context using the provided title, description, ratings, and mastery points; the title is required but all other fields are optional. The new outcome is then linked into the outcome group.

If ratings are provided when creating a new outcome, an embedded rubric criterion is included in the new outcome. This criterion's mastery_points default to the maximum points in the highest rating if not specified in the mastery_points parameter. Any ratings lacking a description are given a default of "No description". Any ratings lacking a point value are given a default of 0. If no ratings are provided, the mastery_points parameter is ignored.

Request Parameters:

  • outcome_id
    Optional, Integer

    The ID of the existing outcome to link.

  • title
    Optional, String

    The title of the new outcome. Required if outcome_id is absent.

  • description
    Optional, String

    The description of the new outcome.

  • vendor_guid
    Optional, String

    A custom GUID for the learning standard.

  • mastery_points
    Optional, Integer

    The mastery threshold for the embedded rubric criterion.

  • ratings[][description]
    Optional, String

    The description of a rating level for the embedded rubric criterion.

  • ratings[][points]
    Optional, Integer

    The points corresponding to a rating level for the embedded rubric criterion.

Example Request:

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes/1.json' \
     -X PUT \ 
     -H "Authorization: Bearer <token>"

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes.json' \
     -X POST \ 
     -F 'title=Outcome Title' \ 
     -F 'description=Outcome description' \
     -F 'vendor_guid=customid9000' \
     -F 'mastery_points=3' \ 
     -F 'ratings[][description]=Exceeds Expectations' \ 
     -F 'ratings[][points]=5' \ 
     -F 'ratings[][description]=Meets Expectations' \ 
     -F 'ratings[][points]=3' \ 
     -F 'ratings[][description]=Does Not Meet Expectations' \ 
     -F 'ratings[][points]=0' \ 
     -H "Authorization: Bearer <token>"

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes.json' \
     -X POST \ 
     --data-binary '{
           "title": "Outcome Title",
           "description": "Outcome description",
           "vendor_guid": "customid9000",
           "mastery_points": 3,
           "ratings": [
             { "description": "Exceeds Expectations", "points": 5 },
             { "description": "Meets Expectations", "points": 3 },
             { "description": "Does Not Meet Expectations", "points": 0 }
           ]
         }' \ 
     -H "Content-Type: application/json" \ 
     -H "Authorization: Bearer <token>"
Returns a OutcomeLink

Unlink an outcome OutcomeGroupsApiController#unlink

DELETE /api/v1/global/outcome_groups/:id/outcomes/:outcome_id

DELETE /api/v1/accounts/:account_id/outcome_groups/:id/outcomes/:outcome_id

DELETE /api/v1/courses/:course_id/outcome_groups/:id/outcomes/:outcome_id

Unlinking an outcome only deletes the outcome itself if this was the last link to the outcome in any group in any context. Aligned outcomes cannot be deleted; as such, if this is the last link to an aligned outcome, the unlinking will fail.

Example Request:

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes/1.json' \
     -X DELETE \ 
     -H "Authorization: Bearer <token>"
Returns a OutcomeLink

List subgroups OutcomeGroupsApiController#subgroups

GET /api/v1/global/outcome_groups/:id/subgroups

GET /api/v1/accounts/:account_id/outcome_groups/:id/subgroups

GET /api/v1/courses/:course_id/outcome_groups/:id/subgroups

List the immediate OutcomeGroup children of the outcome group. Paginated.

Returns a list of OutcomeGroups

Create a subgroup OutcomeGroupsApiController#create

POST /api/v1/global/outcome_groups/:id/subgroups

POST /api/v1/accounts/:account_id/outcome_groups/:id/subgroups

POST /api/v1/courses/:course_id/outcome_groups/:id/subgroups

Creates a new empty subgroup under the outcome group with the given title and description.

Request Parameters:

  • title
    String

    The title of the new outcome group.

  • description
    Optional, String

    The description of the new outcome group.

  • vendor_guid
    Optional, String

    A custom GUID for the learning standard

Example Request:

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/subgroups.json' \
     -X POST \ 
     -F 'title=Outcome Group Title' \ 
     -F 'description=Outcome group description' \
     -F 'vendor_guid=customid9000' \
     -H "Authorization: Bearer <token>"

curl 'https://<canvas>/api/v1/accounts/1/outcome_groups/1/subgroups.json' \
     -X POST \ 
     --data-binary '{
           "title": "Outcome Group Title",
           "description": "Outcome group description",
           "vendor_guid": "customid9000"
         }' \ 
     -H "Content-Type: application/json" \ 
     -H "Authorization: Bearer <token>"
Returns a OutcomeGroup

Import an outcome group OutcomeGroupsApiController#import

POST /api/v1/global/outcome_groups/:id/import

POST /api/v1/accounts/:account_id/outcome_groups/:id/import

POST /api/v1/courses/:course_id/outcome_groups/:id/import

Creates a new subgroup of the outcome group with the same title and description as the source group, then creates links in that new subgroup to the same outcomes that are linked in the source group. Recurses on the subgroups of the source group, importing them each in turn into the new subgroup.

Allows you to copy organizational structure, but does not create copies of the outcomes themselves, only new links.

The source group must be either global, from the same context as this outcome group, or from an associated account. The source group cannot be the root outcome group of its context.

Request Parameters:

  • source_outcome_group_id
    Integer

    The ID of the source outcome group.

Example Request:

curl 'https://<canvas>/api/v1/accounts/2/outcome_groups/3/import.json' \
     -X POST \ 
     -F 'source_outcome_group_id=2' \ 
     -H "Authorization: Bearer <token>"
Returns a OutcomeGroup

Get outcome results OutcomeResultsController#index

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

GET /api/v1/courses/:course_id/outcome_results

Gets the outcome results for users and outcomes in the specified context.

Request Parameters:

  • user_ids[]
    Optional, Integer

    If specified, only the users whose ids are given will be included in the results. it is an error to specify an id for a user who is not a student in the context

  • outcome_ids[]
    Optional, Integer

    If specified, only the outcomes whose ids are given will be included in the results. it is an error to specify an id for an outcome which is not linked to the context.

  • include[]
    Optional, String, "alignments"|"outcomes"|"outcomes.alignments"|"outcome_groups"|"outcome_links"|"outcome_paths"|"users"

    Specify additional collections to be side loaded with the result. "alignments" includes only the alignments referenced by the returned results. "outcomes.alignments" includes all alignments referenced by outcomes in the context.

Example Response:

{
  outcome_results: [OutcomeResult]
}

Get outcome result rollups OutcomeResultsController#rollups

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

GET /api/v1/courses/:course_id/outcome_rollups

Gets the outcome rollups for the users and outcomes in the specified context.

Request Parameters:

  • aggregate
    Optional, String, "course"

    If specified, instead of returning one rollup for each user, all the user rollups will be combined into one rollup for the course that will contain the average rollup score for each outcome.

  • user_ids[]
    Optional, Integer

    If specified, only the users whose ids are given will be included in the results or used in an aggregate result. it is an error to specify an id for a user who is not a student in the context

  • outcome_ids[]
    Optional, Integer

    If specified, only the outcomes whose ids are given will be included in the results. it is an error to specify an id for an outcome which is not linked to the context.

  • include[]
    Optional, String, "courses"|"outcomes"|"outcomes.alignments"|"outcome_groups"|"outcome_links"|"outcome_paths"|"users"

    Specify additional collections to be side loaded with the result.

Example Response:

{
  "rollups": [OutcomeRollup],
  "linked": {
    // (Optional) Included if include[] has outcomes
    "outcomes": [Outcome],

    // (Optional) Included if aggregate is not set and include[] has users
    "users": [User],

    // (Optional) Included if aggregate is 'course' and include[] has courses
    "courses": [Course]

    // (Optional) Included if include[] has outcome_groups
    "outcome_groups": [OutcomeGroup],

    // (Optional) Included if include[] has outcome_links
    "outcome_links": [OutcomeLink]

    // (Optional) Included if include[] has outcome_paths
    "outcome_paths": [OutcomePath]

    // (Optional) Included if include[] has outcomes.alignments
    "outcomes.alignments": [OutcomeAlignment]
  }
}

Show an outcome OutcomesApiController#show

GET /api/v1/outcomes/:id

Returns the details of the outcome with the given id.

Returns a Outcome

Update an outcome OutcomesApiController#update

PUT /api/v1/outcomes/:id

Modify an existing outcome. Fields not provided are left as is; unrecognized fields are ignored.

If any new ratings are provided, the combination of all new ratings provided completely replace any existing embedded rubric criterion; it is not possible to tweak the ratings of the embedded rubric criterion.

A new embedded rubric criterion's mastery_points default to the maximum points in the highest rating if not specified in the mastery_points parameter. Any new ratings lacking a description are given a default of "No description". Any new ratings lacking a point value are given a default of 0.

Request Parameters:

  • title
    Optional, String

    The new outcome title.

  • description
    Optional, String

    The new outcome description.

  • vendor_guid
    Optional, String

    A custom GUID for the learning standard.

  • mastery_points
    Optional, Integer

    The new mastery threshold for the embedded rubric criterion.

  • ratings[][description]
    Optional, String

    The description of a new rating level for the embedded rubric criterion.

  • ratings[][points]
    Optional, Integer

    The points corresponding to a new rating level for the embedded rubric criterion.

Example Request:

curl 'https://<canvas>/api/v1/outcomes/1.json' \
     -X PUT \ 
     -F 'title=Outcome Title' \ 
     -F 'description=Outcome description' \
     -F 'vendor_guid=customid9001' \
     -F 'mastery_points=3' \ 
     -F 'ratings[][description]=Exceeds Expectations' \ 
     -F 'ratings[][points]=5' \ 
     -F 'ratings[][description]=Meets Expectations' \ 
     -F 'ratings[][points]=3' \ 
     -F 'ratings[][description]=Does Not Meet Expectations' \ 
     -F 'ratings[][points]=0' \ 
     -H "Authorization: Bearer <token>"

curl 'https://<canvas>/api/v1/outcomes/1.json' \
     -X PUT \ 
     --data-binary '{
           "title": "Outcome Title",
           "description": "Outcome description",
           "vendor_guid": "customid9001",
           "mastery_points": 3,
           "ratings": [
             { "description": "Exceeds Expectations", "points": 5 },
             { "description": "Meets Expectations", "points": 3 },
             { "description": "Does Not Meet Expectations", "points": 0 }
           ]
         }' \ 
     -H "Content-Type: application/json" \ 
     -H "Authorization: Bearer <token>"
Returns a Outcome

Show front page WikiPagesApiController#show_front_page

GET /api/v1/courses/:course_id/front_page

GET /api/v1/groups/:group_id/front_page

Retrieve the content of the front page

Example Request:

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/123/front_page
Returns a Page

Update/create front page WikiPagesApiController#update_front_page

PUT /api/v1/courses/:course_id/front_page

PUT /api/v1/groups/:group_id/front_page

Update the title or contents of the front page

Request Parameters:

  • wiki_page[title]
    Optional, String

    The title for the new page. NOTE: changing a page's title will change its url. The updated url will be returned in the result.

  • wiki_page[body]
    String

    The content for the new page.

  • wiki_page[hide_from_students]
    Optional, Boolean

    Whether the page should be hidden from students.

    Note: when draft state is enabled, attempts to set hide_from_students will be ignored and the value returned will always be the inverse of the published value.

  • wiki_page[editing_roles]
    Optional, String, "teachers"|"students"|"members"|"public"

    Which user roles are allowed to edit this page. Any combination of these roles is allowed (separated by commas).

    "teachers"

    Allows editing by teachers in the course.

    "students"

    Allows editing by students in the course.

    "members"

    For group wikis, allows editing by members of the group.

    "public"

    Allows editing by any user.

  • wiki_page[notify_of_update]
    Optional, Boolean

    Whether participants should be notified when this page changes.

  • wiki_page[published]
    Optional, Boolean

    Whether the page is published (true) or draft state (false).

    Note: when draft state is disabled, attempts to set published will be ignored and the value returned will always be the inverse of the hide_from_students value.

Example Request:

curl -X PUT -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/front_page?wiki_page[body]=Updated+body+text
Returns a Page

List pages WikiPagesApiController#index

GET /api/v1/courses/:course_id/pages

GET /api/v1/groups/:group_id/pages

List the wiki pages associated with a course or group

Request Parameters:

  • sort
    Optional, String, "title"|"created_at"|"updated_at"

    Sort results by this field.

  • order
    Optional, String, "asc"|"desc"

    The sorting order. Defaults to 'asc'.

  • search_term
    Optional, String

    The partial title of the pages to match and return.

  • published
    Optional, Boolean

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

Example Request:

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/123/pages?sort=title&order=asc
Returns a list of Pages

Create page WikiPagesApiController#create

POST /api/v1/courses/:course_id/pages

POST /api/v1/groups/:group_id/pages

Create a new wiki page

Request Parameters:

  • wiki_page[title]
    String

    The title for the new page.

  • wiki_page[body]
    String

    The content for the new page.

  • wiki_page[hide_from_students]
    Boolean

    Whether the page should be hidden from students.

    Note: when draft state is enabled, attempts to set hide_from_students will be ignored and the value returned will always be the inverse of the published value.

  • wiki_page[editing_roles]
    Optional, String, "teachers"|"students"|"members"|"public"

    Which user roles are allowed to edit this page. Any combination of these roles is allowed (separated by commas).

    "teachers"

    Allows editing by teachers in the course.

    "students"

    Allows editing by students in the course.

    "members"

    For group wikis, allows editing by members of the group.

    "public"

    Allows editing by any user.

  • wiki_page[notify_of_update]
    Boolean

    Whether participants should be notified when this page changes.

  • wiki_page[published]
    Optional, Boolean

    Whether the page is published (true) or draft state (false).

    Note: when draft state is disabled, attempts to set published will be ignored and the value returned will always be the inverse of the hide_from_students value.

  • wiki_page[front_page]
    Optional, Boolean

    Set an unhidden page as the front page (if true)

Example Request:

curl -X POST -H 'Authorization: Bearer <token>' \ 
https://<canvas>/api/v1/courses/123/pages?wiki_page[title]=New+page&wiki_page[body]=New+body+text
Returns a Page

Show page WikiPagesApiController#show

GET /api/v1/courses/:course_id/pages/:url

GET /api/v1/groups/:group_id/pages/:url

Retrieve the content of a wiki page

Example Request:

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/123/pages/my-page-url
Returns a Page

Update/create page WikiPagesApiController#update

PUT /api/v1/courses/:course_id/pages/:url

PUT /api/v1/groups/:group_id/pages/:url

Update the title or contents of a wiki page

Request Parameters:

  • wiki_page[title]
    String

    The title for the new page. NOTE: changing a page's title will change its url. The updated url will be returned in the result.

  • wiki_page[body]
    String

    The content for the new page.

  • wiki_page[hide_from_students]
    Boolean

    Whether the page should be hidden from students.

    Note: when draft state is enabled, attempts to set hide_from_students will be ignored and the value returned will always be the inverse of the published value.

  • wiki_page[editing_roles]
    Optional, String, "teachers"|"students"|"members"|"public"

    Which user roles are allowed to edit this page. Any combination of these roles is allowed (separated by commas).

    "teachers"

    Allows editing by teachers in the course.

    "students"

    Allows editing by students in the course.

    "members"

    For group wikis, allows editing by members of the group.

    "public"

    Allows editing by any user.

  • wiki_page[notify_of_update]
    Boolean

    Whether participants should be notified when this page changes.

  • wiki_page[published]
    Optional, Boolean

    Whether the page is published (true) or draft state (false).

    Note: when draft state is disabled, attempts to set published will be ignored and the value returned will always be the inverse of the hide_from_students value.

  • wiki_page[front_page]
    Optional, Boolean

    Set an unhidden page as the front page (if true)

Example Request:

curl -X PUT -H 'Authorization: Bearer <token>' \ 
https://<canvas>/api/v1/courses/123/pages/the-page-url?wiki_page[body]=Updated+body+text
Returns a Page

Delete page WikiPagesApiController#destroy

DELETE /api/v1/courses/:course_id/pages/:url

DELETE /api/v1/groups/:group_id/pages/:url

Delete a wiki page

Example Request:

curl -X DELETE -H 'Authorization: Bearer <token>' \ 
https://<canvas>/api/v1/courses/123/pages/the-page-url
Returns a Page

List revisions WikiPagesApiController#revisions

GET /api/v1/courses/:course_id/pages/:url/revisions

GET /api/v1/groups/:group_id/pages/:url/revisions

List the revisions of a page. Callers must have update rights on the page in order to see page history.

Example Request:

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/pages/the-page-url/revisions
Returns a list of PageRevisions

Show revision WikiPagesApiController#show_revision

GET /api/v1/courses/:course_id/pages/:url/revisions/latest

GET /api/v1/groups/:group_id/pages/:url/revisions/latest

GET /api/v1/courses/:course_id/pages/:url/revisions/:revision_id

GET /api/v1/groups/:group_id/pages/:url/revisions/:revision_id

Retrieve the metadata and optionally content of a revision of the page. Note that retrieving historic versions of pages requires edit rights.

Request Parameters:

  • summary
    Optional, Boolean

    If set, exclude page content from results

Example Request:

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/pages/the-page-url/revisions/latest

curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/pages/the-page-url/revisions/4
Returns a PageRevision

Revert to revision WikiPagesApiController#revert

POST /api/v1/courses/:course_id/pages/:url/revisions/:revision_id

POST /api/v1/groups/:group_id/pages/:url/revisions/:revision_id

Revert a page to a prior revision.

Request Parameters:

  • revision_id
    Integer

    The revision to revert to (use the List Revisions API to see available revisions)

Example Request:

curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/pages/the-page-url/revisions/6
Returns a PageRevision

Query progress ProgressController#show

GET /api/v1/progress/:id

Return completion and status information about an asynchronous job

Returns a Progress

Get available quiz IP filters. Quizzes::QuizIpFiltersController#index

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

GET /api/v1/courses/:course_id/quizzes/:quiz_id/ip_filters

Get a list of available IP filters for this Quiz.

200 OK response code is returned if the request was successful.

Example Response:

{
  "quiz_ip_filters": [QuizIPFilter]
}

Create a question group Quizzes::QuizGroupsController#create

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

POST /api/v1/courses/:course_id/quizzes/:quiz_id/groups

Create a new question group for this quiz

201 Created response code is returned if the creation was successful.

Request Parameters:

  • quiz_groups[][name]
    Optional, String

    The name of the question group.

  • quiz_groups[][pick_count]
    Optional, Integer

    The number of questions to randomly select for this group.

  • quiz_groups[][question_points]
    Optional, Integer

    The number of points to assign to each question in the group.

  • quiz_groups[][assessment_question_bank_id]
    Optional, Integer

    The id of the assessment question bank to pull questions from.

Example Response:

{
  "quiz_groups": [QuizGroup]
}

Update a question group Quizzes::QuizGroupsController#update

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

PUT /api/v1/courses/:course_id/quizzes/:quiz_id/groups/:id

Update a question group

Request Parameters:

  • quiz_groups[][name]
    Optional, String

    The name of the question group.

  • quiz_groups[][pick_count]
    Optional, Integer

    The number of questions to randomly select for this group.

  • quiz_groups[][question_points]
    Optional, Integer

    The number of points to assign to each question in the group.

Example Response:

{
  "quiz_groups": [QuizGroup]
}

Delete a question group Quizzes::QuizGroupsController#destroy

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

DELETE /api/v1/courses/:course_id/quizzes/:quiz_id/groups/:id

Delete a question group

<b>204 No Content<b> response code is returned if the deletion was successful.

Reorder question groups Quizzes::QuizGroupsController#reorder

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

POST /api/v1/courses/:course_id/quizzes/:quiz_id/groups/:id/reorder

Change the order of the quiz questions within the group

<b>204 No Content<b> response code is returned if the reorder was successful.

Request Parameters:

  • order[][id]
    Required, Integer

    The associated item's unique identifier

  • order[][type]
    "question"

    The type of item is always 'question' for a group

Create a quiz report Quizzes::QuizReportsController#create

POST /api/v1/courses/:course_id/quizzes/:quiz_id/reports

Create and return a new report for this quiz. If a previously generated report matches the arguments and is still current (i.e. there have been no new submissions), it will be returned.

Request Parameters:

  • quiz_report[report_type]
    String, "student_analysis"|"item_analysis"

    The type of report to be generated.

  • quiz_report[includes_all_versions]
    Optional, Boolean

    Whether the report should consider all submissions or only the most recent. Defaults to false, ignored for item_analysis.

Returns a QuizReport

Get a quiz report Quizzes::QuizReportsController#show

GET /api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id

Returns the data for a single quiz report.

Returns a QuizReport

Upload a file Quizzes::QuizSubmissionFilesController#create

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

POST /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/self/files

Associate a new quiz submission file

This API endpoint is the first step in uploading a quiz submission file. See the File Upload Documentation for details on the file upload workflow as these parameters are interpreted as per the documentation there.

Request Parameters:

  • name
    String

    The name of the quiz submission file

  • on_duplicate
    String

    How to handle duplicate names

Example Response:

{
  "attachments": [
    {
      "upload_url": "https://some-bucket.s3.amazonaws.com/",
      "upload_params": {
        "key": "/users/1234/files/answer_pic.jpg",
        "acl": "private",
        "Filename": "answer_pic.jpg",
        "AWSAccessKeyId": "some_id",
        "Policy": "some_opaque_string",
        "Signature": "another_opaque_string",
        "Content-Type": "image/jpeg"
      }
    }
  ]
}

Get all quiz submission questions. QuizSubmissionQuestionsController#index

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

GET /api/v1/quiz_submissions/:quiz_submission_id/questions

Get a list of all the question records for this quiz submission.

200 OK response code is returned if the request was successful.

Request Parameters:

  • include[]
    String, "quiz_question"

    Associations to include with the quiz submission question.

Example Response:

{
  "quiz_submission_questions": [QuizSubmissionQuestion]
}

Get a single quiz submission question. QuizSubmissionQuestionsController#show

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

GET /api/v1/quiz_submissions/:quiz_submission_id/questions/:id

Get a single question record.

200 OK response code is returned if the request was successful.

Request Parameters:

  • include[]
    String, "quiz_question"

    Associations to include with the quiz submission question.

Example Response:

{
  "quiz_submission_questions": [QuizSubmissionQuestion]
}

Answering a question. QuizSubmissionQuestionsController#answer

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

PUT /api/v1/quiz_submissions/:quiz_submission_id/questions/:id

Provide or modify an answer to a QuizQuestion.

Request Parameters:

  • attempt
    Integer

    The attempt number of the quiz submission being taken. Note that this must be the latest attempt index, as questions for earlier attempts can not be modified.

  • validation_token
    String

    The unique validation token you received when the Quiz Submission was created.

  • access_code
    Optional, String

    Access code for the Quiz, if any.

  • answer
    Optional, Mixed

    The answer to the question. The type and format of this argument depend on the question type.

    See Appendix: Question Answer Formats for the accepted answer formats for each question type.

Example Request:

{
  "attempt": 1,
  "validation_token": "YOUR_VALIDATION_TOKEN",
  "access_code": null,
  "answer": "Hello World!"
}

Flagging a question. QuizSubmissionQuestionsController#flag

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

PUT /api/v1/quiz_submissions/:quiz_submission_id/questions/:id/flag

Set a flag on a quiz question to indicate that you want to return to it later.

Request Parameters:

  • attempt
    Integer

    The attempt number of the quiz submission being taken. Note that this must be the latest attempt index, as questions for earlier attempts can not be modified.

  • validation_token
    String

    The unique validation token you received when the Quiz Submission was created.

  • access_code
    Optional, String

    Access code for the Quiz, if any.

Example Request:

{
  "attempt": 1,
  "validation_token": "YOUR_VALIDATION_TOKEN",
  "access_code": null
}

Unflagging a question. QuizSubmissionQuestionsController#unflag

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

PUT /api/v1/quiz_submissions/:quiz_submission_id/questions/:id/unflag

Remove the flag that you previously set on a quiz question after you've returned to it.

Request Parameters:

  • attempt
    Integer

    The attempt number of the quiz submission being taken. Note that this must be the latest attempt index, as questions for earlier attempts can not be modified.

  • validation_token
    String

    The unique validation token you received when the Quiz Submission was created.

  • access_code
    Optional, String

    Access code for the Quiz, if any.

Example Request:

{
  "attempt": 1,
  "validation_token": "YOUR_VALIDATION_TOKEN",
  "access_code": null
}

Get all quiz submissions. Quizzes::QuizSubmissionsApiController#index

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

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions

Get a list of all submissions for this quiz.

200 OK response code is returned if the request was successful.

Request Parameters:

  • include[]
    String, "submission"|"quiz"|"user"

    Associations to include with the quiz submission.

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

Get a single quiz submission. Quizzes::QuizSubmissionsApiController#show

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

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id

Get a single quiz submission.

200 OK response code is returned if the request was successful.

Request Parameters:

  • include[]
    String, "submission"|"quiz"|"user"

    Associations to include with the quiz submission.

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

Create the quiz submission (start a quiz-taking session) Quizzes::QuizSubmissionsApiController#create

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

POST /api/v1/courses/:course_id/quizzes/:quiz_id/submissions

Start taking a Quiz by creating a QuizSubmission which you can use to answer questions and submit your answers.

Responses

  • 200 OK if the request was successful

  • 400 Bad Request if the quiz is locked

  • 403 Forbidden if an invalid access code is specified

  • 403 Forbidden if the Quiz's IP filter restriction does not pass

  • 409 Conflict if a QuizSubmission already exists for this user and quiz

Request Parameters:

  • access_code
    Optional, String

    Access code for the Quiz, if any.

  • preview
    Optional, Boolean

    Whether this should be a preview QuizSubmission and not count towards the user's course record. Teachers only.

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

Update student question scores and comments. Quizzes::QuizSubmissionsApiController#update

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

PUT /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id

Update the amount of points a student has scored for questions they've answered, provide comments for the student about their answer(s), or simply fudge the total score by a specific amount of points.

Responses

  • 200 OK if the request was successful

  • 403 Forbidden if you are not a teacher in this course

  • 400 Bad Request if the attempt parameter is missing or invalid

  • 400 Bad Request if the specified QS attempt is not yet complete

Request Parameters:

  • attempt
    Integer

    The attempt number of the quiz submission that should be updated. This attempt MUST be already completed.

  • fudge_points
    Optional, Float

    Amount of positive or negative points to fudge the total score by.

  • questions
    Optional, Hash

    A set of scores and comments for each question answered by the student. The keys are the question IDs, and the values are hashes of `score` and `comment` entries. See Appendix: Manual Scoring for more on this parameter.

Example Request:

{
  "quiz_submissions": [{
    "attempt": 1,
    "fudge_points": -2.4,
    "questions": {
      "1": {
        "score": 2.5,
        "comment": "This can't be right, but I'll let it pass this one time."
      },
      "2": {
        "score": 0,
        "comment": "Good thinking. Almost!"
      }
    }
  }]
}

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

See Also:

Complete the quiz submission (turn it in). Quizzes::QuizSubmissionsApiController#complete

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

POST /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id/complete

Complete the quiz submission by marking it as complete and grading it. When the quiz submission has been marked as complete, no further modifications will be allowed.

Responses

  • 200 OK if the request was successful

  • 403 Forbidden if an invalid access code is specified

  • 403 Forbidden if the Quiz's IP filter restriction does not pass

  • 403 Forbidden if an invalid token is specified

  • 400 Bad Request if the QS is already complete

  • 400 Bad Request if the attempt parameter is missing

  • 400 Bad Request if the attempt parameter is not the latest attempt

Request Parameters:

  • attempt
    Integer

    The attempt number of the quiz submission that should be completed. Note that this must be the latest attempt index, as earlier attempts can not be modified.

  • validation_token
    String

    The unique validation token you received when this Quiz Submission was created.

  • access_code
    Optional, String

    Access code for the Quiz, if any.

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

List questions in a quiz Quizzes::QuizQuestionsController#index

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

GET /api/v1/courses/:course_id/quizzes/:quiz_id/questions

Returns the list of QuizQuestions in this quiz.

Returns a list of QuizQuestions

Get a single quiz question Quizzes::QuizQuestionsController#show

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

GET /api/v1/courses/:course_id/quizzes/:quiz_id/questions/:id

Returns the quiz question with the given id

Request Parameters:

  • id
    Required, Integer

    The quiz question unique identifier.

Returns a QuizQuestion

Create a single quiz question Quizzes::QuizQuestionsController#create

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

POST /api/v1/courses/:course_id/quizzes/:quiz_id/questions

Create a new quiz question for this quiz

Request Parameters:

  • question[question_name]
    Required, String

    The name of the question.

  • question[question_text]
    Required, String

    The text of the question.

  • question[quiz_group_id]
    Optional, Integer

    The id of the quiz group to assign the question to.

  • question[question_type]
    "calculated_question"|"essay_question"|"file_upload_question"|"fill_in_multiple_blanks_question"|"matching_question"|"multiple_answers_question"|"multiple_choice_question"|"multiple_dropdowns_question"|"numerical_question"|"short_answer_question"|"text_only_question"

    The type of question. Multiple optional fields depend upon the type of question to be used.

  • question[position]
    Optional, Integer

    The order in which the question will be displayed in the quiz in relation to other questions.

  • question[points_possible]
    Optional, Integer

    The maximum amount of points received for answering this question correctly.

  • question[correct_comments]
    Optional, String

    The comment to display if the student answers the question correctly.

  • question[incorrect_comments]
    Optional, String

    The comment to display if the student answers incorrectly.

  • question[neutral_comments]
    Optional, String

    The comment to display regardless of how the student answered.

  • question[text_after_answers]
    Optional, String
  • question[answers]
    Optional, [Answer]
Returns a QuizQuestion

Update an existing quiz question Quizzes::QuizQuestionsController#update

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

PUT /api/v1/courses/:course_id/quizzes/:quiz_id/questions/:id

Updates an existing quiz question for this quiz

Request Parameters:

  • quiz_id
    Required, Integer

    The associated quiz's unique identifier.

  • id
    Required, Integer

    The quiz question's unique identifier.

  • question[question_name]
    Required, String

    The name of the question.

  • question[question_text]
    Required, String

    The text of the question.

  • question[quiz_group_id]
    Optional, Integer

    The id of the quiz group to assign the question to.

  • question[question_type]
    "calculated_question"|"essay_question"|"file_upload_question"|"fill_in_multiple_blanks_question"|"matching_question"|"multiple_answers_question"|"multiple_choice_question"|"multiple_dropdowns_question"|"numerical_question"|"short_answer_question"|"text_only_question"

    The type of question. Multiple optional fields depend upon the type of question to be used.

  • question[position]
    Optional, Integer

    The order in which the question will be displayed in the quiz in relation to other questions.

  • question[points_possible]
    Optional, Integer

    The maximum amount of points received for answering this question correctly.

  • question[correct_comments]
    Optional, String

    The comment to display if the student answers the question correctly.

  • question[incorrect_comments]
    Optional, String

    The comment to display if the student answers incorrectly.

  • question[neutral_comments]
    Optional, String

    The comment to display regardless of how the student answered.

  • question[text_after_answers]
    Optional, String
  • question[answers]
    Optional, [Answer]
Returns a QuizQuestion

Delete a quiz question Quizzes::QuizQuestionsController#destroy

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

DELETE /api/v1/courses/:course_id/quizzes/:quiz_id/questions/:id

<b>204 No Content<b> response code is returned if the deletion was successful.

Request Parameters:

  • quiz_id
    Required, Integer

    The associated quiz's unique identifier

  • id
    Required, Integer

    The quiz question's unique identifier

List quizzes in a course Quizzes::QuizzesApiController#index

GET /api/v1/courses/:course_id/quizzes

Returns the list of Quizzes in this course.

Request Parameters:

  • search_term
    Optional, String

    The partial title of the quizzes to match and return.

Example Request:

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

Get a single quiz Quizzes::QuizzesApiController#show

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

Returns the quiz with the given id.

Returns a Quiz

Create a quiz Quizzes::QuizzesApiController#create

POST /api/v1/courses/:course_id/quizzes

Create a new quiz for this course.

Request Parameters:

  • quiz[title]
    String

    The quiz title.

  • quiz[description]
    String

    A description of the quiz.

  • quiz[quiz_type]
    "practice_quiz"|"assignment"|"graded_survey"|"survey"

    The type of quiz.

  • quiz[assignment_group_id]
    Integer

    The assignment group id to put the assignment in. Defaults to the top assignment group in the course. Only valid if the quiz is graded, i.e. if quiz_type is "assignment" or "graded_survey".

  • quiz[time_limit]
    Integer

    Time limit to take this quiz, in minutes. Set to null for no time limit. Defaults to null.

  • quiz[shuffle_answers]
    Boolean

    If true, quiz answers for multiple choice questions will be randomized for each student. Defaults to false.

  • quiz[hide_results]
    Optional, String, "always"|"until_after_last_attempt"

    Dictates whether or not quiz results are hidden from students. If null, students can see their results after any attempt. If "always", students can never see their results. If "until_after_last_attempt", students can only see results after their last attempt. (Only valid if allowed_attempts > 1). Defaults to null.

  • quiz[show_correct_answers]
    Optional, Boolean

    Only valid if hide_results=null If false, hides correct answers from students when quiz results are viewed. Defaults to true.

  • quiz[show_correct_answers_at]
    Optional, Timestamp

    Only valid if show_correct_answers=true If set, the correct answers will be visible by students only after this date, otherwise the correct answers are visible once the student hands in their quiz submission.

  • quiz[hide_correct_answers_at]
    Optional, Timestamp

    Only valid if show_correct_answers=true If set, the correct answers will stop being visible once this date has passed. Otherwise, the correct answers will be visible indefinitely.

  • quiz[allowed_attempts]
    Optional, Integer

    Number of times a student is allowed to take a quiz. Set to -1 for unlimited attempts. Defaults to 1.

  • quiz[scoring_policy]
    String, "keep_highest"|"keep_latest"

    Required and only valid if allowed_attempts > 1. Scoring policy for a quiz that students can take multiple times. Defaults to "keep_highest".

  • quiz[one_question_at_a_time]
    Optional, Boolean

    If true, shows quiz to student one question at a time. Defaults to false.

  • quiz[cant_go_back]
    Optional, Boolean

    Only valid if one_question_at_a_time=true If true, questions are locked after answering. Defaults to false.

  • quiz[access_code]
    Optional, String

    Restricts access to the quiz with a password. For no access code restriction, set to null. Defaults to null.

  • quiz[ip_filter]
    Optional, String

    Restricts access to the quiz to computers in a specified IP range. Filters can be a comma-separated list of addresses, or an address followed by a mask

    Examples:

    "192.168.217.1"
    "192.168.217.1/24"
    "192.168.217.1/255.255.255.0"

    For no IP filter restriction, set to null. Defaults to null.

  • quiz[due_at]
    Timestamp

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

  • quiz[lock_at]
    Timestamp

    The day/time the quiz is locked for students. Accepts times in ISO 8601 format, e.g. 2011-10-21T18:48Z.

  • quiz[unlock_at]
    Timestamp

    The day/time the quiz is unlocked for students. Accepts times in ISO 8601 format, e.g. 2011-10-21T18:48Z.

  • quiz[published]
    Boolean

    Whether the quiz should have a draft state of published or unpublished. NOTE: If students have started taking the quiz, or there are any submissions for the quiz, you may not unpublish a quiz and will recieve an error.

Returns a Quiz

Edit a quiz Quizzes::QuizzesApiController#update

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

Modify an existing quiz. See the documentation for quiz creation.

Additional arguments:

Request Parameters:

  • quiz[notify_of_update]
    Boolean

    If true, notifies users that the quiz has changed. Defaults to true

Returns a Quiz

Delete a quiz Quizzes::QuizzesApiController#destroy

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

Reorder quiz items Quizzes::QuizzesApiController#reorder

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

POST /api/v1/courses/:course_id/quizzes/:id/reorder

Change order of the quiz questions or groups within the quiz

<b>204 No Content<b> response code is returned if the reorder was successful.

Request Parameters:

  • order[][id]
    Required, Integer

    The associated item's unique identifier

  • order[][type]
    "question"|"group"

    The type of item is either 'question' or 'group'

List roles RoleOverridesController#api_index

GET /api/v1/accounts/:account_id/roles

List the roles available to an account.

Request Parameters:

  • account_id
    String

    The id of the account to retrieve roles for.

  • state[]
    String, "active"|"inactive"

    Filter by role state. If this argument is omitted, only 'active' roles are returned.

Returns a list of Roles

Get a single role RoleOverridesController#show

GET /api/v1/accounts/:account_id/roles/:role

Retrieve information about a single role

Request Parameters:

  • account_id
    String

    The id of the account containing the role

  • role
    String

    The name and unique identifier for the role

Returns a Role

Create a new role RoleOverridesController#add_role

POST /api/v1/accounts/:account_id/roles

Create a new course-level or account-level role.

Request Parameters:

  • role
    String

    Label and unique identifier for the role.

  • base_role_type
    Optional, String, "AccountMembership"|"StudentEnrollment"|"TeacherEnrollment"|"TaEnrollment"|"ObserverEnrollment"|"DesignerEnrollment"

    Specifies the role type that will be used as a base for the permissions granted to this role.

    Defaults to 'AccountMembership' if absent

  • permissions[<X>][explicit]
    Optional, Boolean
  • permissions[<X>][enabled]
    Optional, Boolean

    If explicit is 1 and enabled is 1, permission <X> will be explicitly granted to this role. If explicit is 1 and enabled has any other value (typically 0), permission <X> will be explicitly denied to this role. If explicit is any other value (typically 0) or absent, or if enabled is absent, the value for permission <X> will be inherited from upstream. Ignored if permission <X> is locked upstream (in an ancestor account).

    May occur multiple times with unique values for <X>. Recognized permission names for <X> are:

    [For Account-Level Roles Only]
    become_user                      -- Become other users
    manage_account_memberships       -- Add/remove other admins for the account
    manage_account_settings          -- Manage account-level settings
    manage_alerts                    -- Manage global alerts
    manage_courses                   -- Manage ( add / edit / delete ) courses
    manage_developer_keys            -- Manage developer keys
    manage_global_outcomes           -- Manage learning outcomes
    manage_jobs                      -- Manage background jobs
    manage_role_overrides            -- Manage permissions
    manage_storage_quotas            -- Set storage quotas for courses, groups, and users
    manage_sis                       -- Import and manage SIS data
    manage_site_settings             -- Manage site-wide and plugin settings
    manage_user_logins               -- Modify login details for users
    read_course_content              -- View course content
    read_course_list                 -- View the list of courses
    read_messages                    -- View notifications sent to users
    site_admin                       -- Use the Site Admin section and admin all other accounts
    view_error_reports               -- View error reports
    view_statistics                  -- View statistics
    manage_feature_flags             -- Enable or disable features at an account level
    
    [For both Account-Level and Course-Level roles]
     Note: Applicable enrollment types for course-level roles are given in brackets:
           S = student, T = teacher, A = TA, D = designer, O = observer.
           Lower-case letters indicate permissions that are off by default.
           A missing letter indicates the permission cannot be enabled for the role
           or any derived custom roles.
    change_course_state              -- [ TaD ] Change course state
    comment_on_others_submissions    -- [sTAD ] View all students' submissions and make comments on them
    create_collaborations            -- [STADo] Create student collaborations
    create_conferences               -- [STADo] Create web conferences
    manage_admin_users               -- [ Tad ] Add/remove other teachers, course designers or TAs to the course
    manage_assignments               -- [ TADo] Manage (add / edit / delete) assignments and quizzes
    manage_calendar                  -- [sTADo] Add, edit and delete events on the course calendar
    manage_content                   -- [ TADo] Manage all other course content
    manage_files                     -- [ TADo] Manage (add / edit / delete) course files
    manage_grades                    -- [ TA  ] Edit grades
    manage_groups                    -- [ TAD ] Manage (create / edit / delete) groups
    manage_interaction_alerts        -- [ Ta  ] Manage alerts
    manage_outcomes                  -- [sTaDo] Manage learning outcomes
    manage_sections                  -- [ TaD ] Manage (create / edit / delete) course sections
    manage_students                  -- [ TAD ] Add/remove students for the course
    manage_user_notes                -- [ TA  ] Manage faculty journal entries
    manage_rubrics                   -- [ TAD ] Edit assessing rubrics
    manage_wiki                      -- [ TADo] Manage wiki (add / edit / delete pages)
    read_forum                       -- [STADO] View discussions
    moderate_forum                   -- [sTADo] Moderate discussions (delete/edit others' posts, lock topics)
    post_to_forum                    -- [STADo] Post to discussions
    read_question_banks              -- [ TADo] View and link to question banks
    read_reports                     -- [ TAD ] View usage reports for the course
    read_roster                      -- [STADo] See the list of users
    read_sis                         -- [sTa  ] Read SIS data
    send_messages                    -- [STADo] Send messages to individual course members
    send_messages_all                -- [sTADo] Send messages to the entire class
    view_all_grades                  -- [ TAd ] View all grades
    view_group_pages                 -- [sTADo] View the group pages of all student groups
    

    Some of these permissions are applicable only for roles on the site admin account, on a root account, or for course-level roles with a particular base role type; if a specified permission is inapplicable, it will be ignored.

    Additional permissions may exist based on installed plugins.

  • permissions[<X>][locked]
    Optional, Boolean

    If the value is 1, permission <X> will be locked downstream (new roles in subaccounts cannot override the setting). For any other value, permission <X> is left unlocked. Ignored if permission <X> is already locked upstream. May occur multiple times with unique values for <X>.

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/roles.json' \
     -H "Authorization: Bearer <token>" \ 
     -F 'role=New Role' \ 
     -F 'permissions[read_course_content][explicit]=1' \ 
     -F 'permissions[read_course_content][enabled]=1' \ 
     -F 'permissions[read_course_list][locked]=1' \ 
     -F 'permissions[read_question_banks][explicit]=1' \ 
     -F 'permissions[read_question_banks][enabled]=0' \ 
     -F 'permissions[read_question_banks][locked]=1'
Returns a Role

Deactivate a role RoleOverridesController#remove_role

DELETE /api/v1/accounts/:account_id/roles/:role

Deactivates a custom role. This hides it in the user interface and prevents it from being assigned to new users. Existing users assigned to the role will continue to function with the same permissions they had previously. Built-in roles cannot be deactivated.

Request Parameters:

  • role
    String

    Label and unique identifier for the role.

Returns a Role

Activate a role RoleOverridesController#activate_role

POST /api/v1/accounts/:account_id/roles/:role/activate

Re-activates an inactive role (allowing it to be assigned to new users)

Request Parameters:

  • role
    String

    Label and unique identifier for the role.

Returns a Role

Update a role RoleOverridesController#update

PUT /api/v1/accounts/:account_id/roles/:role

Update permissions for an existing role.

Recognized roles are:

  • TeacherEnrollment

  • StudentEnrollment

  • TaEnrollment

  • ObserverEnrollment

  • DesignerEnrollment

  • AccountAdmin

  • Any previously created custom role

Request Parameters:

  • permissions[<X>][explicit]
    Optional, Boolean
  • permissions[<X>][enabled]
    Optional, Boolean

    These arguments are described in the documentation for the add_role method.

Example Request:

curl https://<canvas>/api/v1/accounts/:account_id/roles/TaEnrollment \ 
  -X PUT \ 
  -H 'Authorization: Bearer <access_token>' \ 
  -F 'permissions[manage_groups][explicit]=1' \ 
  -F 'permissions[manage_groups][enabled]=1' \ 
  -F 'permissions[manage_groups][locked]=1' \ 
  -F 'permissions[send_messages][explicit]=1' \ 
  -F 'permissions[send_messages][enabled]=0'
Returns a Role

Get SIS import list SisImportsApiController#index

GET /api/v1/accounts/:account_id/sis_imports

Returns the list of SIS imports for an account

Examples:
  curl 'https://<canvas>/api/v1/accounts/<account_id>/sis_imports' \
      -H "Authorization: Bearer <token>"
Returns a list of SisImports

Import SIS data SisImportsApiController#create

POST /api/v1/accounts/:account_id/sis_imports

Import SIS data into Canvas. Must be on a root account with SIS imports enabled.

For more information on the format that's expected here, please see the "SIS CSV" section in the API docs.

Request Parameters:

  • import_type
    Optional, String

    Choose the data format for reading SIS data. With a standard Canvas install, this option can only be 'instructure_csv', and if unprovided, will be assumed to be so. Can be part of the query string.

  • attachment

    There are two ways to post SIS import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request.

    'attachment' is required for multipart/form-data style posts. Assumed to be SIS data from a file upload form field named 'attachment'.

    Examples:

    curl -F attachment=@<filename> -H "Authorization: Bearer <token>" \
        'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv'

    If you decide to do a raw post, you can skip the 'attachment' argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the 'extension' argument.

    Examples:

    curl -H 'Content-Type: application/octet-stream' --data-binary @<filename>.zip \
        -H "Authorization: Bearer <token>" \
        'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv&extension=zip'
    
    curl -H 'Content-Type: application/zip' --data-binary @<filename>.zip \
        -H "Authorization: Bearer <token>" \
        'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv'
    
    curl -H 'Content-Type: text/csv' --data-binary @<filename>.csv \
        -H "Authorization: Bearer <token>" \
        'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv'
    
    curl -H 'Content-Type: text/csv' --data-binary @<filename>.csv \
        -H "Authorization: Bearer <token>" \
        'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv&batch_mode=1&batch_mode_term_id=15'
  • extension
    Optional,String

    Recommended for raw post request style imports. This field will be used to distinguish between zip, xml, csv, and other file format extensions that would usually be provided with the filename in the multipart post request scenario. If not provided, this value will be inferred from the Content-Type, falling back to zip-file format if all else fails.

  • batch_mode
    Optional,Boolean

    If set, this SIS import will be run in batch mode, deleting any data previously imported via SIS that is not present in this latest import. See the SIS CSV Format page for details.

  • batch_mode_term_id
    Optional,String

    Limit deletions to only this term. Required if batch mode is enabled.

  • override_sis_stickiness
    Optional,Boolean

    Many fields on records in Canvas can be marked "sticky," which means that when something changes in the UI apart from the SIS, that field gets "stuck." In this way, by default, SIS imports do not override UI changes. If this field is present, however, it will tell the SIS import to ignore "stickiness" and override all fields.

  • add_sis_stickiness
    Optional,Boolean

    This option, if present, will process all changes as if they were UI changes. This means that "stickiness" will be added to changed fields. This option is only processed if 'override_sis_stickiness' is also provided.

  • clear_sis_stickiness
    Optional,Boolean

    This option, if present, will clear "stickiness" from all fields touched by this import. Requires that 'override_sis_stickiness' is also provided. If 'add_sis_stickiness' is also provided, 'clear_sis_stickiness' will overrule the behavior of 'add_sis_stickiness'

Returns a SisImport

Get SIS import status SisImportsApiController#show

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

Get the status of an already created SIS import.

Examples:
  curl 'https://<canvas>/api/v1/accounts/<account_id>/sis_imports/<sis_import_id>' \
      -H "Authorization: Bearer <token>"
Returns a SisImport

Find recipients SearchController#recipients

GET /api/v1/conversations/find_recipients

GET /api/v1/search/recipients

Find valid recipients (users, courses and groups) that the current user can send messages to. The /api/v1/search/recipients path is the preferred endpoint, /api/v1/conversations/find_recipients is deprecated.

Pagination is supported.

Request Parameters:

  • search
    String

    Search terms used for matching users/courses/groups (e.g. "bob smith"). If multiple terms are given (separated via whitespace), only results matching all terms will be returned.

  • context
    String

    Limit the search to a particular course/group (e.g. "course_3" or "group_4").

  • exclude[]
    String

    Array of ids to exclude from the search. These may be user ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. exclude[]=1&exclude=2&exclude[]=course_3

  • type
    String, "user"|"context"

    Limit the search just to users or contexts (groups/courses).

  • user_id
    Integer

    Search for a specific user id. This ignores the other above parameters, and will never return more than one result.

  • from_conversation_id
    Integer

    When searching by user_id, only users that could be normally messaged by this user will be returned. This parameter allows you to specify a conversation that will be referenced for a shared context -- if both the current user and the searched user are in the conversation, the user will be returned. This is used to start new side conversations.

  • permissions[]
    String

    Array of permission strings to be checked for each matched context (e.g. "send_messages"). This argument determines which permissions may be returned in the response; it won't prevent contexts from being returned if they don't grant the permission(s).

API response field:

  • id

    The unique identifier for the user/context. For groups/courses, the id is prefixed by "group_"/"course_" respectively.

  • name

    The name of the user/context

  • avatar_url

    Avatar image url for the user/context

  • type
    "context"|"course"|"section"|"group"|"user"|null

    Type of recipients to return, defaults to null (all). "context" encompasses "course", "section" and "group"

  • types[]

    Array of recipient types to return (see type above), e.g. types[]=user&types=course

  • user_count

    Only set for contexts, indicates number of messageable users

  • common_courses

    Only set for users. Hash of course ids and enrollment types for each course to show what they share with this user

  • common_groups

    Only set for users. Hash of group ids and enrollment types for each group to show what they share with this user

  • permissions[]

    Only set for contexts. Mapping of requested permissions that the context grants the current user, e.g. { send_messages: true }

Example Response:

[
  {"id": "group_1", "name": "the group", "type": "context", "user_count": 3},
  {"id": 2, "name": "greg", "common_courses": {}, "common_groups": {"1": ["Member"]}}
]

List course sections SectionsController#index

GET /api/v1/courses/:course_id/sections

Returns the list of sections for this course.

Request Parameters:

  • include[]
    Optional, String, "students"|"avatar_url"
    • "students": Associations to include with the group. Note: this is only available if you have permission to view users or grades in the course

    • "avatar_url": Include the avatar URLs for students returned.

Returns a list of Sections

Create course section SectionsController#create

POST /api/v1/courses/:course_id/sections

Creates a new section for this course.

Request Parameters:

  • course_section[name]
    String

    The name of the section

  • course_section[sis_section_id]
    Optional, String

    The sis ID of the section

  • course_section[start_at]
    Optional, DateTime

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

  • course_section[end_at]
    Optional, DateTime

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

Returns a Section

Cross-list a Section SectionsController#crosslist

POST /api/v1/sections/:id/crosslist/:new_course_id

Move the Section to another course. The new course may be in a different account (department), but must belong to the same root account (institution).

Returns a Section

De-cross-list a Section SectionsController#uncrosslist

DELETE /api/v1/sections/:id/crosslist

Undo cross-listing of a Section, returning it to its original course.

Returns a Section

Edit a section SectionsController#update

PUT /api/v1/sections/:id

Modify an existing section. See the documentation for create API action.

Returns a Section

Get section information SectionsController#show

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

GET /api/v1/sections/:id

Gets details about a specific section

Returns a Section

Delete a section SectionsController#destroy

DELETE /api/v1/sections/:id

Delete an existing section. Returns the former Section.

Returns a Section

Get Kaltura config ServicesApiController#show_kaltura_config

GET /api/v1/services/kaltura

Return the config information for the Kaltura plugin in json format.

API response field:

  • enabled

    Enabled state of the Kaltura plugin

  • domain

    Main domain of the Kaltura instance (This is the URL where the Kaltura API resides)

  • resources_domain

    Kaltura URL for grabbing thumbnails and other resources

  • rtmp_domain

    Hostname to be used for RTMP recording

  • partner_id

    Partner ID used for communicating with the Kaltura instance

Example Response:

# For an enabled Kaltura plugin:
{
  'domain': 'kaltura.example.com',
  'enabled': true,
  'partner_id': '123456',
  'resource_domain': 'cdn.kaltura.example.com',
  'rtmp_domain': 'rtmp.example.com'
}

# For a disabled or unconfigured Kaltura plugin:
{
  'enabled': false
}

Start Kaltura session ServicesApiController#start_kaltura_session

POST /api/v1/services/kaltura_session

Start a new Kaltura session, so that new media can be recorded and uploaded to this Canvas instance's Kaltura instance.

API response field:

  • ks

    The kaltura session id, for use in the kaltura v3 API. This can be used in the uploadtoken service, for instance, to upload a new media file into kaltura.

Example Response:

{
  'ks': '1e39ad505f30c4fa1af5752b51bd69fe'
}

Upload a file SubmissionCommentsApiController#create_file

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/comments/files

Upload a file to attach to a submission comment

See the File Upload Documentation for details on the file upload workflow.

The final step of the file upload workflow will return the attachment data, including the new file id. The caller can then PUT the file_id to the submission API to attach it to a comment

Submit an assignment SubmissionsController#create

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

POST /api/v1/sections/:section_id/assignments/:assignment_id/submissions

Make a submission for an assignment. You must be enrolled as a student in the course/section to do this.

All online turn-in submission types are supported in this API. However, there are a few things that are not yet supported:

  • Files can be submitted based on a file ID of a user or group file. However, there is no API yet for listing the user and group files, or uploading new files via the API. A file upload API is coming soon.

  • Media comments can be submitted, however, there is no API yet for creating a media comment to submit.

  • Integration with Google Docs is not yet supported.

Request Parameters:

  • comment[text_comment]
    String

    Include a textual comment with the submission.

  • submission[submission_type]
    String, "online_text_entry"|"online_url"|"online_upload"|"media_recording"

    The type of submission being made. The assignment submission_types must include this submission type as an allowed option, or the submission will be rejected with a 400 error.

    The submission_type given determines which of the following parameters is used. For instance, to submit a URL, submission must be set to "online_url", otherwise the submission parameter will be ignored.

  • submission[body]
    String

    Submit the assignment as an HTML document snippet. Note this HTML snippet will be sanitized using the same ruleset as a submission made from the Canvas web UI. The sanitized HTML will be returned in the response as the submission body. Requires a submission_type of "online_text_entry".

  • submission[url]
    String

    Submit the assignment as a URL. The URL scheme must be "http" or "https", no "ftp" or other URL schemes are allowed. If no scheme is given (e.g. "www.example.com") then "http" will be assumed. Requires a submission_type of "online_url".

  • submission[file_ids][]
    Integer

    Submit the assignment as a set of one or more previously uploaded files residing in the submitting user's files section (or the group's files section, for group assignments).

    To upload a new file to submit, see the submissions Upload a file API.

    Requires a submission_type of "online_upload".

  • submission[media_comment_id]
    Integer

    The media comment id to submit. Media comment ids can be submitted via this API, however, note that there is not yet an API to generate or list existing media comments, so this functionality is currently of limited use.

    Requires a submission_type of "media_recording".

  • submission[media_comment_type]
    String, "audio"|"video"

    The type of media comment being submitted.

List assignment submissions SubmissionsApiController#index

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

GET /api/v1/sections/:section_id/assignments/:assignment_id/submissions

Get all existing submissions for an assignment.

Request Parameters:

  • include[]
    String, "submission_history"|"submission_comments"|"rubric_assessment"|"assignment"

    Associations to include with the group.

API response field:

  • assignment_id

    The unique identifier for the assignment.

  • user_id

    The id of the user who submitted the assignment.

  • grader_id

    The id of the user who graded the assignment.

  • submitted_at

    The timestamp when the assignment was submitted, if an actual submission has been made.

  • score

    The raw score for the assignment submission.

  • attempt

    If multiple submissions have been made, this is the attempt number.

  • body

    The content of the submission, if it was submitted directly in a text field.

  • grade

    The grade for the submission, translated into the assignment grading scheme (so a letter grade, for example).

  • grade_matches_current_submission

    A boolean flag which is false if the student has re-submitted since the submission was last graded.

  • preview_url

    Link to the URL in canvas where the submission can be previewed. This will require the user to log in.

  • url

    If the submission was made as a URL.

  • late

    Whether the submission was made after the applicable due date.

List submissions for multiple assignments SubmissionsApiController#for_students

GET /api/v1/courses/:course_id/students/submissions

GET /api/v1/sections/:section_id/students/submissions

Get all existing submissions for a given set of students and assignments.

Request Parameters:

  • student_ids[]
    String

    List of student ids to return submissions for. If this argument is omitted, return submissions for the calling user. Students may only list their own submissions. Observers may only list those of associated students. The special id "all" will return submissions for all students in the course/section as appropriate.

  • assignment_ids[]
    String

    List of assignments to return submissions for. If none are given, submissions for all assignments are returned.

  • grouped
    Boolean

    If this argument is present, the response will be grouped by student, rather than a flat array of submissions.

  • include[]
    String, "submission_history"|"submission_comments"|"rubric_assessment"|"assignment"|"total_scores"

    Associations to include with the group. `total_scores` requires the `grouped` argument.

Example Response:

# Without grouped:

[
  { "assignment_id": 100, grade: 5, "user_id": 1, ... },
  { "assignment_id": 101, grade: 6, "user_id": 2, ... }

# With grouped:

[
  {
    "user_id": 1,
    "submissions": [
      { "assignment_id": 100, grade: 5, ... },
      { "assignment_id": 101, grade: 6, ... }
    ]
  }
]

Get a single submission SubmissionsApiController#show

GET /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id

GET /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id

Get a single submission, based on user id.

Request Parameters:

  • include[]
    String, "submission_history"|"submission_comments"|"rubric_assessment"

    Associations to include with the group.

Upload a file SubmissionsApiController#create_file

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/files

POST /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id/files

Upload a file to a submission.

This API endpoint is the first step in uploading a file to a submission as a student. See the File Upload Documentation for details on the file upload workflow.

The final step of the file upload workflow will return the attachment data, including the new file id. The caller can then POST to submit the online_upload assignment with these file ids.

Grade or comment on a submission SubmissionsApiController#update

PUT /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id

PUT /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id

Comment on and/or update the grading for a student's assignment submission. If any submission or rubric_assessment arguments are provided, the user must have permission to manage grades in the appropriate context (course or section).

Request Parameters:

  • comment[text_comment]
    String

    Add a textual comment to the submission.

  • comment[group_comment]
    Optional, Boolean

    Whether or not this comment should be sent to the entire group (defaults to false). Ignored if this is not a group assignment or if no text_comment is provided.

  • comment[media_comment_id]
    Integer

    Add an audio/video comment to the submission. Media comments can be added via this API, however, note that there is not yet an API to generate or list existing media comments, so this functionality is currently of limited use.

  • comment[media_comment_type]
    String, "audio"|"video"

    The type of media comment being added.

  • comment[file_ids][]
    Optional,Integer

    Attach files to this comment that were previously uploaded using the Submission Comment API's files action

  • submission[posted_grade]
    String

    Assign a score to the submission, updating both the "score" and "grade" fields on the submission record. This parameter can be passed in a few different formats:

    points

    A floating point or integral value, such as "13.5". The grade

    will be interpreted directly as the score of the assignment.
    Values above assignment.points_possible are allowed, for awarding
    extra credit.
    percentage

    A floating point value appended with a percent sign, such as

    "40%". The grade will be interpreted as a percentage score on the
    assignment, where 100% == assignment.points_possible. Values above 100%
    are allowed, for awarding extra credit.
    letter grade

    A letter grade, following the assignment's defined letter

    grading scheme. For example, "A-". The resulting score will be the high
    end of the defined range for the letter grade. For instance, if "B" is
    defined as 86% to 84%, a letter grade of "B" will be worth 86%. The
    letter grade will be rejected if the assignment does not have a defined
    letter grading scheme. For more fine-grained control of scores, pass in
    points or percentage rather than the letter grade.
    "pass/complete/fail/incomplete"

    A string value of "pass" or "complete"

    will give a score of 100%. "fail" or "incomplete" will give a score of
    0.

    Note that assignments with grading_type of "pass_fail" can only be assigned a score of 0 or assignment.points_possible, nothing inbetween. If a posted_grade in the "points" or "percentage" format is sent, the grade will only be accepted if the grade equals one of those two values.

  • rubric_assessment
    RubricAssessment

    Assign a rubric assessment to this assignment submission. The sub-parameters here depend on the rubric for the assignment. The general format is, for each row in the rubric:

    rubric_assessment[points]

    The points awarded for this row.

    rubric_assessment[comments]

    Comments to add for this row.

    For example, if the assignment rubric is (in JSON format):

    [
      {
        'id': 'crit1',
        'points': 10,
        'description': 'Criterion 1',
        'ratings':
        [
          { 'description': 'Good', 'points': 10 },
          { 'description': 'Poor', 'points': 3 }
        ]
      },
      {
        'id': 'crit2',
        'points': 5,
        'description': 'Criterion 2',
        'ratings':
        [
          { 'description': 'Complete', 'points': 5 },
          { 'description': 'Incomplete', 'points': 0 }
        ]
      }
    ]

    Then a possible set of values for rubric_assessment would be:

    rubric_assessment[crit1][points]=3&rubric_assessment[crit2][points]=5&rubric_assessment[crit2][comments]=Well%20Done.

List available tabs for a course or group TabsController#index

GET /api/v1/courses/:course_id/tabs

GET /api/v1/groups/:group_id/tabs

Returns a list of navigation tabs available in the current context.

Request Parameters:

  • include[]
    String, "external"

    Optionally include external tool tabs in the returned list of tabs (Only has effect for courses, not groups)

Example Request:

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/<course_id>/tabs\?include\="external"

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

Example Response:

[
  {
    "html_url": "/courses/1",
    "id": "home",
    "label": "Home",
    "position": 1,
    "visibility": "public",
    "type": "internal"
  },
  {
    "html_url": "/courses/1/external_tools/4",
    "id": "context_external_tool_4",
    "label": "WordPress",
    "hidden": true,
    "visibility": "public",
    "position": 2,
    "type": "external"
  },
  {
    "html_url": "/courses/1/grades",
    "id": "grades",
    "label": "Grades",
    "position": 3,
    "hidden": true
    "visibility": amdin
    "type": "internal"
  }
]

Update a tab for a course TabsController#update

PUT /api/v1/courses/:course_id/tabs/:tab_id

Home and Settings tabs are not manageable, and can't be hidden or moved

Returns a tab object

Request Parameters:

  • position
    Integer

    The new position of the tab, 1-based

  • hidden

    \ true, or false.

Example Request:

curl https://<canvas>/api/v1/courses/<course_id>/tabs/tab_id \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'hidden=true' \
  -d 'position=2' // 1 based
Returns a Tab

List users in account UsersController#index

GET /api/v1/accounts/:account_id/users

Retrieve the list of users associated with this account.

Request Parameters:

  • search_term
    Optional, String

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

Returns a list of Users

List the activity stream UsersController#activity_stream

GET /api/v1/users/self/activity_stream

GET /api/v1/users/activity_stream

Returns the current user's global activity stream, paginated.

There are many types of objects that can be returned in the activity stream. All object types have the same basic set of shared attributes:

{
  'created_at': '2011-07-13T09:12:00Z',
  'updated_at': '2011-07-25T08:52:41Z',
  'id': 1234,
  'title': 'Stream Item Subject',
  'message': 'This is the body text of the activity stream item. It is plain-text, and can be multiple paragraphs.',
  'type': 'DiscussionTopic|Conversation|Message|Submission|Conference|Collaboration|...',
  'read_state': false,
  'context_type': 'course', // course|group
  'course_id': 1,
  'group_id': null,
  'html_url': "http://..." // URL to the Canvas web UI for this stream item
}

In addition, each item type has its own set of attributes available.

DiscussionTopic:

{
  'type': 'DiscussionTopic',
  'discussion_topic_id': 1234,
  'total_root_discussion_entries': 5,
  'require_initial_post': true,
  'user_has_posted': true,
  'root_discussion_entries': {
    ...
  }
}

For DiscussionTopic, the message is truncated at 4kb.

Announcement:

{
  'type': 'Announcement',
  'announcement_id': 1234,
  'total_root_discussion_entries': 5,
  'require_initial_post': true,
  'user_has_posted': null,
  'root_discussion_entries': {
    ...
  }
}

For Announcement, the message is truncated at 4kb.

Conversation:

{
  'type': 'Conversation',
  'conversation_id': 1234,
  'private': false,
  'participant_count': 3,
}

Message:

{
  'type': 'Message',
  'message_id': 1234,
  'notification_category': 'Assignment Graded'
}

Submission:

Returns an Submission with its Course and Assignment data.

Conference:

{
  'type': 'Conference',
  'web_conference_id': 1234
}

Collaboration:

{
  'type': 'Collaboration',
  'collaboration_id': 1234
}

Activity stream summary UsersController#activity_stream_summary

GET /api/v1/users/self/activity_stream/summary

Returns a summary of the current user's global activity stream.

Example Response:

[
  {
    "type": "DiscussionTopic",
    "unread_count": 2,
    "count": 7
  },
  {
    "type": "Conversation",
    "unread_count": 0,
    "count": 3
  }
]

List the TODO items UsersController#todo_items

GET /api/v1/users/self/todo

Returns the current user's list of todo items, as seen on the user dashboard.

There is a limit to the number of items returned.

The `ignore` and `ignore_permanently` URLs can be used to update the user's preferences on what items will be displayed. Performing a DELETE request against the `ignore` URL will hide that item from future todo item requests, until the item changes. Performing a DELETE request against the `ignore_permanently` URL will hide that item forever.

Example Response:

[
  {
    'type': 'grading',        // an assignment that needs grading
    'assignment': { .. assignment object .. },
    'ignore': '.. url ..',
    'ignore_permanently': '.. url ..',
    'html_url': '.. url ..',
    'needs_grading_count': 3, // number of submissions that need grading
    'context_type': 'course', // course|group
    'course_id': 1,
    'group_id': null,
  },
  {
    'type' => 'submitting',   // an assignment that needs submitting soon
    'assignment' => { .. assignment object .. },
    'ignore' => '.. url ..',
    'ignore_permanently' => '.. url ..',
    'html_url': '.. url ..',
    'context_type': 'course',
    'course_id': 1,
  }
]

List upcoming assignments, calendar events UsersController#upcoming_events

GET /api/v1/users/self/upcoming_events

Returns the current user's upcoming events, i.e. the same things shown in the dashboard 'Coming Up' sidebar.

Example Response:

[
  {
    "id"=>597,
    "title"=>"Upcoming Course Event",
    "description"=>"Attendance is correlated with passing!",
    "start_at"=>"2013-04-27T14:33:14Z",
    "end_at"=>"2013-04-27T14:33:14Z",
    "location_name"=>"Red brick house",
    "location_address"=>"110 Top of the Hill Dr.",
    "all_day"=>false,
    "all_day_date"=>nil,
    "created_at"=>"2013-04-26T14:33:14Z",
    "updated_at"=>"2013-04-26T14:33:14Z",
    "workflow_state"=>"active",
    "context_code"=>"course_12938",
    "child_events_count"=>0,
    "child_events"=>[],
    "parent_event_id"=>nil,
    "hidden"=>false,
    "url"=>"http://www.example.com/api/v1/calendar_events/597",
    "html_url"=>"http://www.example.com/calendar?event_id=597&include_contexts=course_12938"
  },
  {
    "id"=>"assignment_9729",
    "title"=>"Upcoming Assignment",
    "description"=>nil,
    "start_at"=>"2013-04-28T14:47:32Z",
    "end_at"=>"2013-04-28T14:47:32Z",
    "all_day"=>false,
    "all_day_date"=>"2013-04-28",
    "created_at"=>"2013-04-26T14:47:32Z",
    "updated_at"=>"2013-04-26T14:47:32Z",
    "workflow_state"=>"published",
    "context_code"=>"course_12942",
    "assignment"=>{
      "id"=>9729,
      "name"=>"Upcoming Assignment",
      "description"=>nil,
      "points_possible"=>10,
      "due_at"=>"2013-04-28T14:47:32Z",
      "assignment_group_id"=>2439,
      "automatic_peer_reviews"=>false,
      "grade_group_students_individually"=>nil,
      "grading_standard_id"=>nil,
      "grading_type"=>"points",
      "group_category_id"=>nil,
      "lock_at"=>nil,
      "peer_reviews"=>false,
      "position"=>1,
      "unlock_at"=>nil,
      "course_id"=>12942,
      "submission_types"=>["none"],
      "muted"=>false,
      "needs_grading_count"=>0,
      "html_url"=>"http://www.example.com/courses/12942/assignments/9729"
    },
    "url"=>"http://www.example.com/api/v1/calendar_events/assignment_9729",
    "html_url"=>"http://www.example.com/courses/12942/assignments/9729"
  }
]

Hide a stream item UsersController#ignore_stream_item

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

Hide the given stream item.

Example Request:

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

Example Response:

{
  "hidden": true
}

Hide all stream items UsersController#ignore_all_stream_items

DELETE /api/v1/users/self/activity_stream

Hide all stream items for the user

Example Request:

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

Example Response:

{
  "hidden": true
}

Upload a file UsersController#create_file

POST /api/v1/users/:user_id/files

Upload a file to the user's personal files section.

This API endpoint is the first step in uploading a file to a user's files. See the File Upload Documentation for details on the file upload workflow.

Note that typically users will only be able to upload files to their own files section. Passing a user_id of self is an easy shortcut to specify the current user.

Create a user UsersController#create

POST /api/v1/accounts/:account_id/users

Create and return a new user and pseudonym for an account.

If you don't have the "Modify login details for users" permission, but self-registration is enabled on the account, you can still use this endpoint to register new users. Certain fields will be required, and others will be ignored (see below).

Request Parameters:

  • user[name]
    Optional, String

    The full name of the user. This name will be used by teacher for grading. Required if this is a self-registration.

  • user[short_name]
    Optional, String

    User's name as it will be displayed in discussions, messages, and comments.

  • user[sortable_name]
    Optional, String

    User's name as used to sort alphabetically in lists.

  • user[time_zone]
    Optional, String

    The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

  • user[locale]
    Optional, String

    The user's preferred language as a two-letter ISO 639-1 code.

  • user[birthdate]
    Optional, Date

    The user's birth date.

  • user[terms_of_use]
    Optional, Boolean

    Whether the user accepts the terms of use. Required if this is a self-registration and this canvas instance requires users to accept the terms (on by default).

  • pseudonym[unique_id]
    String

    User's login ID. If this is a self-registration, it must be a valid email address.

  • pseudonym[password]
    Optional, String

    User's password. Cannot be set during self-registration.

  • pseudonym[sis_user_id]
    Optional, String

    SIS ID for the user's account. To set this parameter, the caller must be able to manage SIS permissions.

  • pseudonym[send_confirmation]
    Optional, Boolean

    Send user notification of account creation if true. Automatically set to true during self-registration.

  • communication_channel[type]
    Optional, String

    The communication channel type, e.g. 'email' or 'sms'.

  • communication_channel[address]
    Optional, String

    The communication channel address, e.g. the user's email address.

  • skip_confirmation
    Optional, Boolean

    Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.

Returns a User

Update user settings. UsersController#settings

GET /api/v1/users/:id/settings

PUT /api/v1/users/:id/settings

Update an existing user's settings.

Request Parameters:

  • manual_mark_as_read
    Boolean

    If true, require user to manually mark discussion posts as read (don't auto-mark as read).

Example Request:

curl 'https://<canvas>/api/v1/users/<user_id>/settings \
  -X PUT \ 
  -F 'manual_mark_as_read=true'
  -H 'Authorization: Bearer <token>'

Edit a user UsersController#update

PUT /api/v1/users/:id

Modify an existing user. To modify a user's login, see the documentation for logins.

Request Parameters:

  • user[name]
    Optional, String

    The full name of the user. This name will be used by teacher for grading.

  • user[short_name]
    Optional, String

    User's name as it will be displayed in discussions, messages, and comments.

  • user[sortable_name]
    Optional, String

    User's name as used to sort alphabetically in lists.

  • user[time_zone]
    Optional, String

    The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

  • user[locale]
    Optional, String

    The user's preferred language as a two-letter ISO 639-1 code.

  • user[avatar][token]
    Optional, String

    A unique representation of the avatar record to assign as the user's current avatar. This token can be obtained from the user avatars endpoint. This supersedes the user[url] argument, and if both are included the url will be ignored. Note: this is an internal representation and is subject to change without notice. It should be consumed with this api endpoint and used in the user update endpoint, and should not be constructed by the client.

  • user[avatar][url]
    Optional, String

    To set the user's avatar to point to an external url, do not include a token and instead pass the url here. Warning: For maximum compatibility, please use 128 px square images.

Example Request:

curl 'https://<canvas>/api/v1/users/133.json' \
     -X PUT \ 
     -F 'user[name]=Sheldon Cooper' \ 
     -F 'user[short_name]=Shelly' \ 
     -F 'user[time_zone]=Pacific Time (US & Canada)' \ 
     -F 'user[avatar][token]=<opaque_token>' \ 
     -H "Authorization: Bearer <token>"
Returns a User

Delete a user UsersController#destroy

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

Delete a user record from Canvas.

WARNING: This API will allow a user to delete themselves. If you do this, you won't be able to make API calls or log into Canvas.

Example Request:

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

Merge user into another user UsersController#merge_into

PUT /api/v1/users/:id/merge_into/:destination_user_id

PUT /api/v1/users/:id/merge_into/accounts/:destination_account_id/users/:destination_user_id

Merge a user into another user. To merge users, the caller must have permissions to manage both users.

When finding users by SIS ids in different accounts the destination_account_id is required.

The account can also be identified by passing the domain in destination_account_id.

Example Request:

curl https://<canvas>/api/v1/users/<user_id>/merge_into/<destination_user_id> \
     -X PUT \
     -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/users/<user_id>/merge_into/accounts/<destination_account_id>/users/<destination_user_id> \
     -X PUT \
     -H 'Authorization: Bearer <token>'
Returns a User

Get user profile ProfileController#settings

GET /api/v1/users/:user_id/profile

Returns user profile data, including user id, name, and profile pic.

When requesting the profile for the user accessing the API, the user's calendar feed URL will be returned as well.

Returns a Profile

List avatar options ProfileController#profile_pics

GET /api/v1/users/:user_id/avatars

Retrieve the possible user avatar options that can be set with the user update endpoint. The response will be an array of avatar records. If the 'type' field is 'attachment', the record will include all the normal attachment json fields; otherwise it will include only the 'url' and 'display_name' fields. Additionally, all records will include a 'type' field and a 'token' field. The following explains each field in more detail

type
"gravatar"|"attachment"|"no_pic"

The type of avatar record, for categorization purposes.

url

The url of the avatar

token

A unique representation of the avatar record which can be used to set the avatar with the user update endpoint. Note: this is an internal representation and is subject to change without notice. It should be consumed with this api endpoint and used in the user update endpoint, and should not be constructed by the client.

display_name

A textual description of the avatar record

id
'attachment' type only

the internal id of the attachment

content-type
'attachment' type only

the content-type of the attachment

filename
'attachment' type only

the filename of the attachment

size
'attachment' type only

the size of the attachment

Example Request:

curl 'https://<canvas>/api/v1/users/1/avatars.json' \
     -H "Authorization: Bearer <token>"

Example Response:

[
  {
    "type":"gravatar",
    "url":"https://secure.gravatar.com/avatar/2284...",
    "token":<opaque_token>,
    "display_name":"gravatar pic"
  },
  {
    "type":"attachment",
    "url":"https://<canvas>/images/thumbnails/12/gpLWJ...",
    "token":<opaque_token>,
    "display_name":"profile.jpg",
    "id":12,
    "content-type":"image/jpeg",
    "filename":"profile.jpg",
    "size":32649
  },
  {
    "type":"no_pic",
    "url":"https://<canvas>/images/dotted_pic.png",
    "token":<opaque_token>,
    "display_name":"no pic"
  }
]
Returns a list of Avatars

List user page views PageViewsController#index

GET /api/v1/users/:user_id/page_views

Return the user's page view history in json format, similar to the available CSV download. Pagination is used as described in API basics section. Page views are returned in descending order, newest to oldest.

Request Parameters:

  • start_time
    Optional, DateTime

    The beginning of the time range from which you want page views.

  • end_time
    Optional, DateTime

    The end of the time range from which you want page views.

Returns a list of PageViews

Store custom data CustomDataController#set_data

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

PUT /api/v1/users/:user_id/custom_data/:scope

Store arbitrary user data as JSON.

Arbitrary JSON data can be stored for a User. A typical scenario would be an external site/service that registers users in Canvas and wants to capture additional info about them. The part of the URL that follows /custom_data/ defines the scope of the request, and it reflects the structure of the JSON data to be stored or retrieved.

A namespace parameter, ns, is used to prevent custom_data collisions between different apps. This parameter is required for all custom_data requests.

A request with Content-Type multipart/form-data or Content-Type application/x-www-form-urlencoded can only be used to store strings.

Example PUT with multipart/form-data data:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/telephone' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data=555-1234' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "555-1234"
}

Subscopes (or, generated scopes) can also be specified by passing values to data.

Example PUT specifying subscopes:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/body/measurements' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data[waist]=32in' \
  -F 'data[inseam]=34in' \
  -F 'data[chest]=40in' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "chest": "40in",
    "waist": "32in",
    "inseam": "34in"
  }
}

Following such a request, subsets of the stored data to be retrieved directly from a subscope.

Example GET from a generated scope

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/body/measurements/chest' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "40in"
}

If you want to store more than just strings (i.e. numbers, arrays, hashes, true, false, and/or null), you must make a request with Content-Type application/json as in the following example.

Example PUT with JSON data:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{
        "ns": "com.my-organization.canvas-app",
        "data": {
          "a-number": 6.02e23,
          "a-bool": true,
          "a-string": "true",
          "a-hash": {"a": {"b": "ohai"}},
          "an-array": [1, "two", null, false]
        }
      }' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "a-number": 6.02e+23,
    "a-bool": true,
    "a-string": "true",
    "a-hash": {
      "a": {
        "b": "ohai"
      }
    },
    "an-array": [1, "two", null, false]
  }
}

If the data is an Object (as it is in the above example), then subsets of the data can be accessed by including the object's (possibly nested) keys in the scope of a GET request.

Example GET with a generated scope:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/a-hash/a/b' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "ohai"
}

On success, this endpoint returns an object containing the data that was stored.

Responds with status code 200 if the scope already contained data, and it was overwritten by the data specified in the request.

Responds with status code 201 if the scope was previously empty, and the data specified in the request was successfully stored there.

Responds with status code 400 if the namespace parameter, ns, is missing or invalid, or if the data parameter is missing.

Responds with status code 409 if the requested scope caused a conflict and data was not stored. This happens when storing data at the requested scope would cause data at an outer scope to be lost. e.g., if /custom_data currently was {"hair": "blonde"}, but you tried to PUT /custom_data/fashion_app/hair/style -F 'data=buzz', then for the request to succeed,the value of /custom_data/fashion_app/hair would have to become a hash, and its old string value would be lost. In this situation, an error object is returned with the following format:

{
  "message": "write conflict for custom_data hash",
  "conflict_scope": "fashion_app/hair",
  "type_at_conflict": "String",
  "value_at_conflict": "blonde"
}

Request Parameters:

  • ns
    String

    The namespace under which to store the data. This should be something other Canvas API apps aren't likely to use, such as a reverse DNS for your organization.

  • data
    JSON

    The data you want to store for the user, at the specified scope. If the data is composed of (possibly nested) JSON objects, scopes will be generated for the (nested) keys (see examples).

Example Request:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/food_app' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data[weight]=81kg' \
  -F 'data[favorites][meat]=pork belly' \
  -F 'data[favorites][dessert]=pistachio ice cream' \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "data": {
    "weight": "81kg",
    "favorites": {
      "meat": "pork belly",
      "dessert": "pistachio ice cream"
    }
  }
}

Load custom data CustomDataController#get_data

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

GET /api/v1/users/:user_id/custom_data/:scope

Load custom user data.

Arbitrary JSON data can be stored for a User. This API call retrieves that data for a (optional) given scope. See Store Custom Data for details and examples.

On success, this endpoint returns an object containing the data that was requested.

Responds with status code 400 if the namespace parameter, ns, is missing or invalid, or if the specified scope does not contain any data.

Request Parameters:

  • ns
    String

    The namespace from which to retrieve the data. This should be something other Canvas API apps aren't likely to use, such as a reverse DNS for your organization.

Example Request:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/food_app/favorites/dessert' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "data": "pistachio ice cream"
}

Delete custom data CustomDataController#delete_data

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

DELETE /api/v1/users/:user_id/custom_data/:scope

Delete custom user data.

Arbitrary JSON data can be stored for a User. This API call deletes that data for a given scope. Without a scope, all custom_data is deleted. See Store Custom Data for details and examples of storage and retrieval.

As an example, we'll store some data, then delete a subset of it.

Example PUT with valid JSON data:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data[fruit][apple]=so tasty' \
  -F 'data[fruit][kiwi]=a bit sour' \
  -F 'data[veggies][root][onion]=tear-jerking' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "fruit": {
      "apple": "so tasty",
      "kiwi": "a bit sour"
    },
    "veggies": {
      "root": {
        "onion": "tear-jerking"
      }
    }
  }
}

Example DELETE:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/fruit/kiwi' \
  -X DELETE \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "a bit sour"
}

Example GET following the above DELETE:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "fruit": {
      "apple": "so tasty"
    },
    "veggies": {
      "root": {
        "onion": "tear-jerking"
      }
    }
  }
}

Note that hashes left empty after a DELETE will get removed from the custom_data store. For example, following the previous commands, if we delete /custom_data/veggies/root/onion, then the entire /custom_data/veggies scope will be removed.

Example DELETE that empties a parent scope:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/veggies/root/onion' \
  -X DELETE \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "tear-jerking"
}

Example GET following the above DELETE:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "fruit": {
      "apple": "so tasty"
    }
  }
}

On success, this endpoint returns an object containing the data that was deleted.

Responds with status code 400 if the namespace parameter, ns, is missing or invalid, or if the specified scope does not contain any data.

Request Parameters:

  • ns
    String

    The namespace from which to delete the data. This should be something other Canvas API apps aren't likely to use, such as a reverse DNS for your organization.

Example Request:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/fruit/kiwi' \
  -X DELETE \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "data": "a bit sour"
}