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.

account_authorization_config[0][auth_type]=cas&
account_authorization_config[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

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

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.

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

Get Authorization Config AccountAuthorizationConfigsController#show

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

Get the specified authorization config

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

Delete Authorization Config AccountAuthorizationConfigsController#destroy

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

Delete the config

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

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

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.

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

Delete discovery url AccountAuthorizationConfigsController#destroy_discovery_url

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

Clear discovery url

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

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

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

Start a Report AccountReportsController#create

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

Generates a report instance for the account.

Request Parameters:

• [parameters]

  The parameters will vary for each 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.

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

Status of a Report AccountReportsController#show

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

Returns the status of a report.

Request Parameters:

• [report_id]

  The report id.

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

Delete a Report AccountReportsController#destroy

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

Deletes a generated report instance.

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

List accounts AccountsController#index

GET /api/v1/accounts

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

  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.

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

  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

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

• completed

  optional

  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

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

• by_subaccounts[]

  optional

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

• hide_enrollmentless_courses

  optional

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

• state[]

  optional

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

• enrollment_term_id

  optional

  If set, only includes courses from the specified term.

Update an account AccountsController#update

PUT /api/v1/accounts/:id

Update an existing account.

Request Parameters:

• account[name]

  optional

  Updates the account name

• account[default_time_zone]

  Optional

  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

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

• account[default_user_storage_quota_mb]

  Optional

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

• account[default_group_storage_quota_mb]

  Optional

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

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'

{
  "id": "1",
  "name": "New account name",
  "default_time_zone": "America/Denver",
  "parent_account_id": null,
  "root_account_id": null,
  "default_storage_quota_mb": 500,
  "default_user_storage_quota_mb": 50
  "default_group_storage_quota_mb": 50
}

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

  The id of the user to promote.

• role

  Optional

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

• send_confirmation

  Optional

  0|1

  Send a notification email to the new admin if set to '1'; send no email if set to '0'. Default is '1'.

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

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

List account admins AdminsController#index

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

List the admins in the account

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.

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

Create an external feed ExternalFeedsController#create

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

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

Create a new external feed for the course or group.

Request Parameters:

• url

  The url to the external rss or atom feed

• header_match

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

• verbosity

  "full", "truncate", "link_only"

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

Delete an external feed ExternalFeedsController#destroy

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

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

Deletes the external feed.

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

List 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, "reservable"|"manageable"

  Defaults to "reservable"

• context_codes[]

  Optional

  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

  Array of additional information to include.

  Allowable values include "appointments" (i.e. calendar event time slots for this appointment group), "child_events" (i.e. reservations of those time slots), "participant_count" (i.e. number of reservations), and "reserved_times" (i.e. 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][]

  Required

  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

  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

  Short title for the appointment group.

• appointment_group[description]

  Optional

  Longer text description of the appointment group.

• appointment_group[location_name]

  Optional

  Location name of the appointment group.

• appointment_group[location_address]

  Optional

  Location address.

• appointment_group[publish]

  Optional

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

• appointment_group[participants_per_appointment]

  Optional

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

• appointment_group[min_appointments_per_participant]

  Optional

  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

  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" means participants cannot see who has signed up for a particular time slot, "protected" means that they can. Defaults to "private".

curl 'http://<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

  Array of additional information to include.

  Allowable values include "child_events" (i.e. reservations of time slots time slots). "appointments" will always be returned (see include[] argument of "List appointment groups" action).

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][]

  Optional

  Array of context codes to add to this appointment group (existing ones cannot be removed).

• appointment_group[sub_context_codes][]

  Optional

  Array of sub context codes to add to this appointment group (existing ones cannot be removed).

• appointment_group[title]

  Optional

  Short title for the appointment group.

• appointment_group[description]

  Optional

  Longer text description of the appointment group.

• appointment_group[location_name]

  Optional

  Location name of the appointment group.

• appointment_group[location_address]

  Optional

  Location address.

• appointment_group[publish]

  Optional

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

• appointment_group[participants_per_appointment]

  Optional

  Maximum number of participants that may register for each time slot. Defaults to null (no limit). Changes will not affect existing reservations.

• appointment_group[min_appointments_per_participant]

  Optional

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

• appointment_group[max_appointments_per_participant]

  Optional

  Maximum number of time slots a user may register for. Changes will not affect existing reservations.

• appointment_group[new_appointments][X][]

  Optional

  Nested array of new start time/end time pairs indicating time slots for this appointment group. Refer to the example request. To remove existing time slots or reservations, use the Calendar Event API.

• appointment_group[participant_visibility]

  Optional, "private"|"protected"

  "private" means participants cannot see who has signed up for a particular time slot, "protected" means that they can.

curl 'http://<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

appointment group.

Request Parameters:

• cancel_reason

  Optional

  Reason for deleting/canceling the

curl 'http://<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.

"discussion_topic" is only valid if "assignments" is also included

Request Parameters:

• include[]

  "assignments","discussion_topic"

  Associations to include with the group.

• override_assignment_dates

  Optional, Boolean

  Apply assignment overrides for each assignment, defaults to true.

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.

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

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

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

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

Delete an assignment AssignmentsController#destroy

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

Delete the given assignment.

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

List assignments AssignmentsApiController#index

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

Returns the list of assignments for the current context.

Request Parameters:

• include[]

  "submission"

  Associations to include with the assignment.

• search_term

  (optional) The partial title of the assignments to match and return.

• override_assignment_dates

  Optional, Boolean

  Apply assignment overrides for each assignment, defaults to true.

Get a single assignment AssignmentsApiController#show

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

Returns the assignment with the given id.

Request Parameters:

• include[]

  "submission"

  Associations to include with the assignment.

• override_assignment_dates

  Optional, Boolean

  Apply assignment overrides to the assignment, defaults to true.

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]

  The assignment name.

• assignment[position]

  Integer

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

• assignment[submission_types]

  Array

  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]

  Array

  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"|"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[published]

  Boolean

  Optional

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

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.

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.

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.

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]

  Timestamp, Optional

  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]

  Timestamp, Optional

  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]

  Timestamp, Optional

  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.

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

Update an assignment override AssignmentOverridesController#update

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]

  [Integer], Optional

  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

  The title of an adhoc

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

• assignment_override[due_at]

  Timestamp, Optional

  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]

  Timestamp, Optional

  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]

  Timestamp, Optional

  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.

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

Delete an assignment override AssignmentOverridesController#destroy

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.

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

Query by pseudonym. AuthenticationAuditApiController#for_pseudonym

GET /api/v1/audit/authentication/pseudonyms/:pseudonym_id

List authentication events for a given pseudonym.

Request Parameters:

• start_time

  Datetime

  optional

  The beginning of the time range

  from which you want events.

• end_time

  Datetime

  optional

  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

  Datetime

  optional

  The beginning of the time range

  from which you want events.

• end_time

  Datetime

  optional

  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

  Datetime

  optional

  The beginning of the time range

  from which you want events.

• end_time

  Datetime

  optional

  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, "event"|"assignment"

  Defaults to "event"

• start_date

  Optional

  Only return events since the start_date (inclusive).

  Defaults to today. The value should be formatted as: yyyy-mm-dd.

• end_date

  Optional

  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

  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]

  Required

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

• calendar_event[title]

  Optional

  Short title for the calendar event

• calendar_event[description]

  Optional

  Longer HTML description of the event

• calendar_event[start_at]

  Optional

  Start date/time of the event

• calendar_event[end_at]

  Optional

  End date/time of the event

• calendar_event[location_name]

  Optional

  Location name of the event

• calendar_event[location_address]

  Optional

  Location address

• calendar_event[time_zone_edited]

  Optional

  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

  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

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

• calendar_event[child_event_data][X][context_code]

  Optional

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

curl 'http://<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]. 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]. Defaults to false. If true, cancel any previous reservation(s) for this participant and appointment group.

curl 'http://<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[title]

  Optional

  Short title for the calendar event

• calendar_event[description]

  Optional

  Longer HTML description of the event

• calendar_event[start_at]

  Optional

  Start date/time of the event

• calendar_event[end_at]

  Optional

  End date/time of the event

• calendar_event[location_name]

  Optional

  Location name of the event

• calendar_event[location_address]

  Optional

  Location address

• calendar_event[time_zone_edited]

  Optional

  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

  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. Note that if any child_event_data is specified, it will replace any existing child events.

• calendar_event[child_event_data][X][end_at]

  Optional

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

• calendar_event[child_event_data][X][context_code]

  Optional

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

• calendar_event[remove_child_events]

  Optional

  Boolean, indicates that all child events (i.e. section-level events) should be removed.

• calendar_event[participants_per_appointment]

  Optional

  Maximum number of participants that may sign up for this time slot. Ignored for regular calendar events or reservations.

curl 'http://<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

  Reason for deleting/canceling the event.

curl 'http://<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 http://<canvas>/api/v1/courses/1/collaborations/1/members

List user/group collections CollectionsController#index

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

GET /api/v1/users/:user_id/collections

GET /api/v1/groups/:group_id/collections

Returns the visible collections for the given group or user, returned most-recently-created first. If the given context is the current user or a group to which the current user belongs, then all collections will be returned, otherwise only public collections will be returned. In the former case, if no collections exist for the context, a default, private collection will be created and returned.

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

List pinnable collections CollectionsController#list

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

GET /api/v1/collections

Returns the list of collections to which the current user has permission to post. For each possible collection context (the current user and each community she belongs to) if no collections exist for the context, a default, private collection will be created and included in the returned list.

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

Get a single collection CollectionsController#show

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

GET /api/v1/collections/:collection_id

Returns information on an individual collection. If the collection is private and the caller doesn't have read access, a 401 is returned.

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

Create a collection CollectionsController#create

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

POST /api/v1/users/:user_id/collections

POST /api/v1/groups/:group_id/collections

Creates a new collection. You can only create collections on your own user, or on a group to which you belong.

Request Parameters:

• name
• visibility

curl -H 'Authorization: Bearer <token>' \ 
     -F name='My Collection' \ 
     -F visibility=public \ 
     https://<canvas>/api/v1/users/self/collections

Edit a collection CollectionsController#update

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

PUT /api/v1/collections/:collection_id

Modify an existing collection. You must have write access to the collection.

Collection visibility cannot be modified once the collection is created.

Request Parameters:

• name
• visibility

  Be advised that setting a public collection to private will permanantly remove all of its followers.

curl -H 'Authorization: Bearer <token>' \ 
     -X PUT \ 
     -F name='My Edited Collection' \ 
     https://<canvas>/api/v1/collections/<collection_id>

Delete a collection CollectionsController#destroy

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

DELETE /api/v1/collections/:collection_id

Deletes a collection and all contained collection items. You must have write access to the collection.

curl -H 'Authorization: Bearer <token>' \ 
     -X DELETE \ 
     https://<canvas>/api/v1/collections/<collection_id>

Follow a collection CollectionsController#follow

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

PUT /api/v1/collections/:collection_id/followers/self

Follow this collection. If the current user is already following the collection, nothing happens. The user must have permissions to view the collection in order to follow it.

Responds with a 401 if the user doesn't have permission to follow the collection, or a 400 if the user can't follow the collection (if it's the user's own collection, for example).

curl https://<canvas>/api/v1/collections/<collection_id>/followers/self \ 
     -X PUT \ 
     -H 'Content-Length: 0' \ 
     -H 'Authorization: Bearer <token>'

{
  following_user_id: 5,
  followed_collection_id: 6,
  created_at: <timestamp>
}

Un-follow a collection CollectionsController#unfollow

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

DELETE /api/v1/collections/:collection_id/followers/self

Stop following this collection. If the current user is not already following the collection, nothing happens.

curl https://<canvas>/api/v1/collections/<collection_id>/followers/self \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'

List collection items CollectionItemsController#index

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

GET /api/v1/collections/:collection_id/items

GET /api/v1/collections/:collection_id/items

Returns the collection items in a collection, most-recently-created first. The user must have read access to the collection.

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

Get an individual collection item CollectionItemsController#show

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

GET /api/v1/collections/items/:item_id

Returns an individual collection item. The user must have read access to the collection.

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

Create or clone a collection item CollectionItemsController#create

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

POST /api/v1/collections/:collection_id/items

Create a new item in this collection. You can also clone an existing item from another collection.

Request Parameters:

• link_url

  The URL of the item to add. This can be any HTTP or HTTPS address. The item_type will be determined by the link_url that is passed in.

  To clone an existing item, pass in the url to that item as returned in the JSON response in the "url" field.

• title

  The title of the item. If no title is provided, Canvas will try to automatically add a relevant title based on the linked content.

• description

  The plain-text description of the item. If no description is provided, Canvas will try to automatically add a relevant description based on the linked content.

• image_url

  The URL of the image to use for this item. If no image url is provided, Canvas will try to automatically determine an image representation for the link. This parameter is ignored if the new item is a clone of an existing item.

• user_comment

  The user's comments on the item. This can be set when cloning an existing item, as well.

curl https://<canvas>/api/v1/collections/<collection_id>/items \ 
     -F link_url="http://www.google.com/" \ 
     -F user_comment="lmgtfy" \ 
     -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/collections/<collection_id>/items \ 
     -F link_url="https://<canvas>/api/v1/collections/items/3" \ 
     -F user_comment="clone of some other item" \ 
     -H 'Authorization: Bearer <token>'

Edit a collection item CollectionItemsController#update

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

PUT /api/v1/collections/items/:item_id

Change a collection item's mutable attributes.

Request Parameters:

• user_comment

curl https://<canvas>/api/v1/collections/items/<item_id> \ 
     -X PUT \ 
     -F user_comment='edited comment' \ 
     -H 'Authorization: Bearer <token>'

Delete a collection item CollectionItemsController#destroy

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

DELETE /api/v1/collections/items/:item_id

Delete a collection item from the collection. This will not delete any clones of the item in other collections.

curl https://<canvas>/api/v1/collections/items/<item_id> \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'

Upvote an item CollectionItemsController#upvote

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

PUT /api/v1/collections/items/:item_id/upvotes/self

Upvote a collection item. If the current user has already upvoted the item, nothing happens and the existing upvote data is returned. Upvotes are shared between the root item and all clones, so if the user has already upvoted another clone of the item, nothing happens.

The upvoted_by_user field on the CollectionItem response data can be used to determine if the user has already upvoted the item.

curl https://<canvas>/api/v1/collections/items/<item_id>/upvotes/self \ 
     -X PUT \ 
     -H 'Content-Length: 0' \ 
     -H 'Authorization: Bearer <token>'

{
  item_id: 7,
  root_item_id: 3,
  user_id: 2,
  created_at: "2012-05-03T18:12:18Z",
}

De-upvote an item CollectionItemsController#remove_upvote

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

DELETE /api/v1/collections/items/:item_id/upvotes/self

Remove the current user's upvote of an item. This is a no-op if the user has not upvoted this item.

curl https://<canvas>/api/v1/collections/items/<item_id>/upvotes/self \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'

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

  The user id for whom you want to retrieve CommMessages

• start_time

  optional

  The beginning of the time range you want to

  retrieve message from.

• end_time

  optional

  The end of the time range you want to retrieve

  messages for.

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.

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

Create a communication channel CommunicationChannelsController#create

POST /api/v1/users/:user_id/communication_channels

Creates a new communication channel for the specified user.

Request Parameters:

• communication_channel[address]

  An email address or SMS number.

• communication_channel[type]

  email|sms

  The type of communication channel.

• skip_confirmation

  Optional

  Only valid for site admins making requests; If '1', 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.

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

Delete a communication channel CommunicationChannelsController#destroy

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

Delete an existing communication channel.

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

List migration issues MigrationIssuesController#index

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

Returns paginated migration issues

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

Get a migration issue MigrationIssuesController#show

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

Returns data on an individual migration issue

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

Update a migration issue MigrationIssuesController#update

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

Update the workflow_state of a migration issue

Request Parameters:

• workflow_state

  Set the workflow_state of the issue, only 'active' and 'resolved' accepted

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

List content migrations ContentMigrationsController#index

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

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

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

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

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

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[source_course_id]

  string

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

• settings[folder_id]

  string

  (optional) The folder to unzip the .zip file into for a zip_file_import. (required if doing .zip file upload)

• settings[overwrite_quizzes]

  boolean

  (optional) Whether to overwrite quizzes with the same identifiers between content packages

• settings[question_bank_id]

  integer

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

• settings[question_bank_name]

  string

  (optional) 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]

  boolean

  (optional) Whether to shift dates

• date_shift_options[old_start_date]

  yyyy-mm-dd

  (optional) The original start date of the source content/course

• date_shift_options[old_end_date]

  yyyy-mm-dd

  (optional) The original end date of the source content/course

• date_shift_options[new_start_date]

  yyyy-mm-dd

  (optional) The new start date for the content/course

• date_shift_options[new_end_date]

  yyyy-mm-dd

  (optional) The new end date for the source content/course

• date_shift_options[day_substitutions][x]

  integer

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

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

Update a content migration ContentMigrationsController#update

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.

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.

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, "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, course_id|group_id|user_id

  When set, only return conversations for the specified course, group or user. The id should be prefixed with its type, e.g. "user_123" or "course_456"

• interleave_submissions

  Boolean, default 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 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.

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

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[]

  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

• subject

  optional

  The subject of the conversation.

  This is ignored when reusing a conversation.

• body

  The message to be sent

• group_conversation

  true|false

  Ignored if there is just one

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

• attachment_ids[]

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

• media_comment_id

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

• media_comment_type

  "audio"|"video"

  Type of the associated

  media file

• mode

  "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, "unread"|"starred"|"archived"

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

• filter

  optional, course_id|group_id|user_id

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

• context_code

  optional

  The course or group that is the context

  for this conversation. Same format as courses or groups in the recipients argument

ConversationsController#batches

GET /api/v1/conversations/batches

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

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

Get a single conversation ConversationsController#show

GET /api/v1/conversations/:id

Returns information for a single conversation. 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, "unread"|"starred"|"archived"

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

• filter

  optional, course_id|group_id|user_id

  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.

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

  Change the subject of this conversation

• conversation[workflow_state]

  "read"|"unread"|"archived"

  Change the state of this conversation

• conversation[subscribed]

  true|false

  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]

  true|false

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

• scope

  optional, "unread"|"starred"|"archived"

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

• filter

  optional, course_id|group_id|user_id

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

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

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

  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

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

Request Parameters:

• body

  The message to be sent

• attachment_ids[]

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

• media_comment_id

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

• media_comment_type

  "audio"|"video"

  Type of the associated

  media file

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

  Array of message ids to be deleted

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

  List of conversations to update. Limited to 500 conversations.

• event

  The action to take on each conversation. Must be one of 'mark_as_read', 'mark_as_unread', 'star', 'unstar', 'archive', 'destroy'

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

Find recipients ConversationsController#find_recipients

GET /api/v1/conversations/find_recipients

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

{'unread_count': '7'}

List your courses CoursesController#index

GET /api/v1/courses

Returns the list of active courses for the current user.

Request Parameters:

• enrollment_type

  optional, "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

  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[]

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

• include[]

  "syllabus_body"

  Optional information to include with each Course.

  When syllabus_body is given the user-generated html for the course syllabus is returned.

• include[]

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

• include[]

  "term"

  Optional information to include with each Course.

  When term is given, the information for the enrollment term for each course is returned.

• state[]

  optional

  If set, only return courses that are in the given state(s).

  Valid states are "unpublished", "available", "completed", and "deleted". By default, "available" is returned for students and observers, and anything except "deleted", for all other enrollment types

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]

  String

  optional

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

• course[course_code]

  String

  optional

  The course code for the course.

• course[start_at]

  Datetime

  optional

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

• course[end_at]

  Datetime

  optional

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

• course[license]

  String

  optional

  The name of the licensing. Should be one of the following abbreviations (a descriptive name is included in parenthesis for reference): 'private' (Private Copyrighted); 'cc_by_nc_nd' (CC Attribution Non-Commercial No Derivatives); 'cc_by_nc_sa' (CC Attribution Non-Commercial Share Alike); 'cc_by_nc' (CC Attribution Non-Commercial); 'cc_by_nd' (CC Attribution No Derivatives); 'cc_by_sa' (CC Attribution Share Alike); 'cc_by' (CC Attribution); 'public_domain' (Public Domain).

• course[is_public]

  Boolean

  optional

  Set to true if course if public.

• course[public_syllabus]

  Boolean

  optional

  Set to true to make the course syllabus public.

• course[public_description]

  String

  optional

  A publicly visible description of the course.

• course[allow_student_wiki_edits]

  Boolean

  optional

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

• course[allow_wiki_comments]

  Boolean

  optional

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

• course[allow_student_forum_attachments]

  Boolean

  optional

  If true, students can attach files to forum posts.

• course[open_enrollment]

  Boolean

  optional

  Set to true if the course is open enrollment.

• course[self_enrollment]

  Boolean

  optional

  Set to true if the course is self enrollment.

• course[restrict_enrollments_to_course_dates]

  Boolean

  optional

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

• course[enroll_me]

  Boolean

  optional

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

• course[sis_course_id]

  String

  optional

  The unique SIS identifier.

• course[hide_final_grades]

  Boolean

  optional

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

• course[apply_assignment_group_weights]

  Boolean

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

• offer

  Boolean

  optional

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

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.

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

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

• enrollment_type

  optional, "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

  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[]

  "email"

  Optional user email.

• include[]

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

• include[]

  "locked"

  Optionally include whether an enrollment is locked.

• include[]

  "avatar_url"

  Optionally include avatar_url.

• include[]

  "test_student"

  Optionally include the course's Test Student,

  if present. Default is to not include Test Student.

• user_id

  optional

  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.

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.

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

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.

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

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

{
  "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. available options are 'delete' and 'conclude.'

Get course settings CoursesController#settings

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

Returns some of a course's settings.

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

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

• `allow_student_discussion_topics` (true|false)

• `allow_student_forum_attachments` (true|false)

• `allow_student_discussion_editing` (true|false)

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[]

  "all_courses"

  Also search recently deleted courses

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

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'

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

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'

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.

{'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 possible items for 'except' and 'only' are: "course_settings", "assignments", "external_tools", "files", "topics", "calendar_events", "quizzes", "wiki_pages", "modules", "outcomes"

The response is the same as the course copy status endpoint

Request Parameters:

• source_course

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

• except[]

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

• only[]

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

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

  Determines the order of the discussion topic list. May be one of "position", or "recent_activity". Defaults to "position".

• scope

  Optional, "locked"|"unlocked"

  Only return discussion topics in the given state. Defaults to including locked and unlocked topics. Filtering is done after pagination, so pages may be smaller than requested if topics are filtered

• only_announcements

  Optional

  Boolean, return announcements instead of discussion topics. Defaults to false

• search_term

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

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
• message
• discussion_type
• 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

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

• lock_at

  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

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

• podcast_has_student_posts

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

• require_initial_post

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

• 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

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

• position_after

  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.

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

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.

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

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

  The updated body of the entry.

curl -X PUT 'http://<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.

curl -X DELETE 'http://<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.

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.

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

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

  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.

curl 'http://<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.

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

  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.

curl 'http://<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.

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

  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.

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

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

curl 'http://<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.

curl 'http://<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

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

curl 'http://<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

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

curl 'http://<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

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

curl 'http://<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

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

curl 'http://<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

curl 'http://<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

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

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[]

  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[]

  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[]

  Filter by enrollment state. Accepted values are 'active', 'invited', and 'creation_pending', 'deleted', 'rejected', 'completed', and 'inactive'. If omitted, 'active' and 'invited' enrollments are returned.

API response field:

• id

  The unique id of the enrollment.

• course_id

  The unique id of the course.

• course_section_id

  The unique id of the user's section.

• enrollment_state

  The state of the user's enrollment in the course.

• limit_privileges_to_course_section

  User can only access his or her own course section.

• root_account_id

  The unique id of the user's account.

• type

  The type of the enrollment.

• role

  The enrollment role, for course-level permissions.

• user_id

  The unique id of the user.

• html_url

  The URL to the Canvas web UI page for this course enrollment.

• grades[html_url]

  The URL to the Canvas web UI page for the user's grades, if this is a student enrollment.

• grades[current_grade]

  The user's current grade in the class. Only included if user has permissions to view this grade.

• grades[final_grade]

  The user's final grade for the class. Only included if user has permissions to view this grade.

• user[id]

  The unique id of the user.

• user[login_id]

  The unique login of the user.

• user[name]

  The name of the user.

• user[short_name]

  The short name of the user.

• user[sortable_name]

  The sortable name of the user.

[
  {
    "id": 1,
    "course_id": 1,
    "course_section_id": 1,
    "enrollment_state": "active",
    "limit_privileges_to_course_section": true,
    "root_account_id": 1,
    "type": "StudentEnrollment",
    "user_id": 1,
    "html_url": "https://...",
    "grades": {
      "html_url": "https://...",
    },
    "user": {
      "id": 1,
      "login_id": "bieberfever@example.com",
      "name": "Justin Bieber",
      "short_name": "Justin B.",
      "sortable_name": "Bieber, Justin"
    }
  },
  {
    "id": 2,
    "course_id": 1,
    "course_section_id": 2,
    "enrollment_state": "active",
    "limit_privileges_to_course_section": false,
    "root_account_id": 1,
    "type": "TeacherEnrollment",
    "user_id": 2,
    "html_url": "https://...",
    "grades": {
      "html_url": "https://...",
    },
    "user": {
      "id": 2,
      "login_id": "changyourmind@example.com",
      "name": "Señor Chang",
      "short_name": "S. Chang",
      "sortable_name": "Chang, Señor"
    }
  },
  {
    "id": 3,
    "course_id": 1,
    "course_section_id": 2,
    "enrollment_state": "active",
    "limit_privileges_to_course_section": false,
    "root_account_id": 1,
    "type": "StudentEnrollment",
    "user_id": 2,
    "html_url": "https://...",
    "grades": {
      "html_url": "https://...",
    },
    "user": {
      "id": 2,
      "login_id": "changyourmind@example.com",
      "name": "Señor Chang",
      "short_name": "S. Chang",
      "sortable_name": "Chang, Señor"
    }
  }
]

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]

  String

  Optional

  Assigns a custom course-level role to the user.

• enrollment[enrollment_state]

  String

  Optional, active|invited

  String

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

• enrollment[course_section_id]

  Integer

  Optional

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

• enrollment[limit_privileges_to_course_section]

  Boolean

  Optional

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

• enrollment[notify]

  Boolean

  Optional

  If false (0 or "false"), a notification will not be sent to the enrolled user. Notifications are sent by default.

Conclude an enrollment EnrollmentsApiController#destroy

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

Delete or conclude an enrollment.

Request Parameters:

• task

  conclude|delete

  String

  The action to take on the enrollment.

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

{
  "root_account_id": 15,
  "id": 75,
  "user_id": 4,
  "course_section_id": 12,
  "limit_privileges_to_course_section": false,
  "enrollment_state": "completed",
  "course_id": 12,
  "type": "StudentEnrollment",
  "html_url": "http://www.example.com/courses/12/users/4",
  "grades": { "html_url": "http://www.example.com/courses/12/grades/4" },
  "associated_user_id": null,
  "updated_at": "2012-04-18T23:08:51Z"
}

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) The partial name of the tools to match and return.

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

  The external id of the tool to launch.

• url

  string

  optional

  The LTI launch url for the external tool.

• assignment_id

  optional

  The assignment id for an assignment launch.

• launch_type

  string

  optional

  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)

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

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

• consumer_key

  string

  The consumer key for the external tool

• shared_secret

  string

  The shared secret with the external tool

• description

  string

  optional

  A description of the tool

• url

  string

  optional

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

• domain

  string

  optional

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

• icon_url

  string

  optional

  The url of the icon to show for this tool

• text

  string

  optional

  The default text to show for this tool

• custom_fields

  string

  optional

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

• account_navigation[url]

  string

  optional

  The url of the external tool for account navigation

• account_navigation[enabled]

  boolean

  optional

  Set this to enable this feature

• account_navigation[text]

  string

  optional

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

• user_navigation[url]

  string

  optional

  The url of the external tool for user navigation

• user_navigation[enabled]

  boolean

  optional

  Set this to enable this feature

• user_navigation[text]

  string

  optional

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

• course_navigation[url]

  string

  optional

  The url of the external tool for course navigation

• course_navigation[enabled]

  boolean

  optional

  Set this to enable this feature

• course_navigation[text]

  string

  optional

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

• course_navigation[visibility]

  string

  optional

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

• course_navigation[default]

  boolean

  optional

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

• editor_button[url]

  string

  optional

  The url of the external tool

• editor_button[enabled]

  boolean

  optional

  Set this to enable this feature

• editor_button[icon_url]

  string

  optional

  The url of the icon to show in the WYSIWYG editor

• editor_button[selection_width]

  string

  optional

  The width of the dialog the tool is launched in

• editor_button[selection_height]

  string

  optional

  The height of the dialog the tool is launched in

• resource_selection[url]

  string

  optional

  The url of the external tool

• resource_selection[enabled]

  boolean

  optional

  Set this to enable this feature

• resource_selection[icon_url]

  string

  optional

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

• resource_selection[selection_width]

  string

  optional

  The width of the dialog the tool is launched in

• resource_selection[selection_height]

  string

  optional

  The height of the dialog the tool is launched in

• config_type

  string

  optional

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

• config_xml

  string

  optional

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

• config_url

  string

  optional

  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"

This would create a tool on this course with two custom fields and a course navigation tab
curl 'http://<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 'http://<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 'http://<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

This would update the specified keys on this external tool
curl -X PUT 'http://<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

This would delete the specified external tool
curl -X DELETE 'http://<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.

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

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.

must be registered in the course.

Request Parameters:

• id

  the ID or SIS ID of the course to add. The current user

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

Remove course from favorites FavoritesController#remove_favorite_course

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

Remove a course from the current user's favorites.

Request Parameters:

• id

  the ID or SIS ID of the course to remove

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

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

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

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

  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) The partial name of the files to match and return.

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

Get file FilesController#api_show

GET /api/v1/files/:id

Returns the standard attachment json object

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

Update file FilesController#api_update

PUT /api/v1/files/:id

Update some settings on the specified file

Request Parameters:

• name

  The new display name of the file

• parent_folder_id

  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

  The datetime to lock the file at

• unlock_at

  The datetime to unlock the file at

• locked

  Flag the file as locked

• hidden

  Flag the file as hidden

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

Delete file FilesController#destroy

DELETE /api/v1/files/:id

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.

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

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:

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

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

Update folder FoldersController#update

PUT /api/v1/folders/:id

Updates a folder

Request Parameters:

• name

  The new name of the folder

• parent_folder_id

  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

  The datetime to lock the folder at

• unlock_at

  The datetime to unlock the folder at

• locked

  Flag the folder as locked

• hidden

  Flag the folder as hidden

• position

  Set an explicit sort position for the folder

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

Create folder FoldersController#create

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

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

  The name of the folder

• parent_folder_id

  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

  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

  The datetime to lock the folder at

• unlock_at

  The datetime to unlock the folder at

• locked

  Flag the folder as locked

• hidden

  Flag the folder as hidden

• position

  Set an explicit sort position for the folder

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

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

Delete folder FoldersController#api_destroy

DELETE /api/v1/folders/:id

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

Request Parameters:

• force

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

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.

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

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

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

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

  Integer, Optional

  The ID of the assignment for which you want to see submissions. If absent, versions of submissions from any assignment in the course are included.

• user_id

  Integer, Optional

  The ID of the user for which you want to see submissions. If absent, versions of submissions from any user in the course are included.

• ascending

  Boolean, Optional

  Returns submission versions in ascending date order (oldest first). If absent, returns submission versions in descending date order (newest first).

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

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

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.

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

Create a Group Category GroupCategoriesController#create

POST /api/v1/accounts/:account_id/group_categories

POST /api/v1/courses/:course_id/group_categories

Create a new group category

Request Parameters:

• name
• self_signup

  Optional

  Course Only

  allow students to sign up for a group themselves

  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

  Course Only

  Limit the maximum number of users in each group. Requires self signup.

• create_group_count

  Optional

  Course Only

  create this number of groups

• split_group_count

  Optional

  Course Only

  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

curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \ 
    -F 'name=Project Groups' \ 
    -H 'Authorization: Bearer <token>'

Update a Group Category GroupCategoriesController#update

PUT /api/v1/group_categories/:group_category_id

Modifies an existing group category.

Request Parameters:

• name
• self_signup

  Optional

  Course Only

  allow students to signup for a group themselves

  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

  Course Only

  Limit the maximum number of users in each group. Requires self signup.

• create_group_count

  Optional

  Course Only

  create this number of groups

• split_group_count

  Optional

  Course Only

  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

curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
    -X PUT \ 
    -F 'name=Project Groups' \ 
    -H 'Authorization: Bearer <token>'

Delete a Group Category GroupCategoriesController#destroy

DELETE /api/v1/group_categories/:group_category_id

Deletes a group category and all groups under it. Protected group categories can not be deleted, i.e. "communities", "student_organized", and "imported".

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

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

List users 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) 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) Set this value to true if you wish only to search unassigned users in the group category

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

Assign unassigned members GroupCategoriesController#assign_unassigned_members

POST /api/v1/group_categories/:group_category_id/assign_unassigned_members

Assign all unassigned members as evenly as possible among the existing student groups.

Request Parameters:

• sync

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

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

# 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

  only include groups that are in this type of

  context. Can be 'Account' or 'Course'

curl https://<canvas>/api/v1/users/self/groups?context_type=Account \ 
     -H 'Authorization: Bearer <token>'

List the groups available in a context. GroupsController#context_index

GET /api/v1/accounts/:account_id/groups

GET /api/v1/courses/:course_id/groups

Returns the list of active groups in the given context that are visible to user.

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

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.

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

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

  the name of the group

• description

  a description of the group

• is_public

  whether the group is public (applies only to community groups)

• join_level

  parent_context_auto_join, parent_context_request, or invitation_only

• storage_quota_mb

  The allowed file storage for the group, in megabytes. This parameter is ignored if the caller does not have the manage_storage_quotas permission.

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

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
• description
• is_public

  Currently you cannot set a group back to private once it has been made public.

• join_level
• avatar_id

  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

  The allowed file storage for the group, in megabytes. This parameter is ignored if the caller does not have the manage_storage_quotas permission.

curl https://<canvas>/api/v1/groups/<group_id> \ 
     -X PUT \ 
     -F 'name=Algebra Teachers' \ 
     -F 'join_level=parent_context_request' \ 
     -H 'Authorization: Bearer <token>'

Delete a group GroupsController#destroy

DELETE /api/v1/groups/:group_id

Deletes a group and removes all members.

curl https://<canvas>/api/v1/groups/<group_id> \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'

Follow a group GroupsController#follow

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

PUT /api/v1/groups/:group_id/followers/self

Follow this group. If the current user is already following the group, nothing happens. The user must have permissions to view the group in order to follow it.

Responds with a 401 if the user doesn't have permission to follow the group.

curl https://<canvas>/api/v1/groups/<group_id>/followers/self \ 
     -X PUT \ 
     -H 'Content-Length: 0' \ 
     -H 'Authorization: Bearer <token>'

{
  following_user_id: 5,
  followed_group_id: 6,
  created_at: <timestamp>
}

Un-follow a group GroupsController#unfollow

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

DELETE /api/v1/groups/:group_id/followers/self

Stop following this group. If the current user is not already following the group, nothing happens.

curl https://<canvas>/api/v1/groups/<group_id>/followers/self \ 
     -X DELETE \ 
     -H 'Authorization: Bearer <token>'

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

  An array of email addresses to be sent invitations

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) The partial name or full ID of the users to match and return in the results list. Must be at least 3 characters.

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

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

  The html content to process

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

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

  Only list memberships with the given

  workflow_states. Allowed values are "accepted", "invited", and "requested". By default it will return all memberships.

curl https://<canvas>/api/v1/groups/<group_id>/memberships \ 
     -F 'filter_states[]=invited&filter_states[]=requested' \ 
     -H 'Authorization: Bearer <token>'

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

curl https://<canvas>/api/v1/groups/<group_id>/memberships \ 
     -F 'user_id=self'
     -H 'Authorization: Bearer <token>'

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

  Currently, the only allowed value is "accepted"

• moderator

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

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.

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]

  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.

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

  The ID of the user to create the login for.

• login[unique_id]

  The unique ID for the new login.

• login[password]

  The new login's password.

• login[sis_user_id]

  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]

  The new unique ID for the login.

• login[password]

  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]

  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.

curl https://<canvas>/api/v1/users/:user_id/logins/:login_id \ 
  -H "Authorization: Bearer <ACCESS-TOKEN>" \ 
  -X DELETE

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

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

• include[]

  "content_details"

  (Requires include) Returns additional details with module items specific to their associated content items.

  Refer to the Module Item specification for more details.

• search_term

  (optional) The partial name of the modules (and module items, if include is specified) to match and return.

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

Show module ContextModulesApiController#show

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

Get information about a single module

Request Parameters:

• include[]

  "items"

  Return module items inline if possible.

  Please refer to the caveats outlined in the List modules endpoint.

• include[]

  "content_details"

  If module items are included, also returns additional details specific to their associated content items.

  Refer to the Module Item specification for more details.

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123

Create a module ContextModulesApiController#create

POST /api/v1/courses/:course_id/modules

Create and return a new module

Request Parameters:

• module[name]

  Required

  The name of the module

• module[unlock_at]

  Optional

  The date the module will unlock

• module[position]

  Optional

  The position of this module in the course (1-based)

• module[require_sequential_progress]

  Optional

  Whether module items must be unlocked in order

• module[prerequisite_module_ids][]

  Optional

  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

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'

Update a module ContextModulesApiController#update

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

Update and return an existing module

Request Parameters:

• module[name]

  Optional

  The name of the module

• module[unlock_at]

  Optional

  The date the module will unlock

• module[position]

  Optional

  The position of the module in the course (1-based)

• module[require_sequential_progress]

  Optional

  Whether module items must be unlocked in order

• module[prerequisite_module_ids][]

  Optional

  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[published]

  Optional

  Whether the module is published and visible to students

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'

Delete module ContextModulesApiController#destroy

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

Delete a module

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id> \
  -X Delete \
  -H 'Authorization: Bearer <token>'

List module items ContextModuleItemsApiController#index

GET /api/v1/courses/:course_id/modules/:module_id/items

List the items in a module

Request Parameters:

• include[]

  "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) The partial title of the items to match and return.

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123/items

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[]

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

curl -H 'Authorization: Bearer <token>' \
     https://<canvas>/api/v1/courses/222/modules/123/items/768

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

  The name of the module item and associated content

• module_item[type]

  Required

  The type of content linked to the item

  one of "File", "Page", "Discussion", "Assignment", "Quiz", "SubHeader", "ExternalUrl", "ExternalTool"

• module_item[content_id]

  Required, except for 'ExternalUrl', 'Page', and 'SubHeader' types

  The id of the content to link to the module item

• module_item[position]

  Optional

  The position of this item in the module (1-based)

• module_item[indent]

  Optional

  0-based indent level; module items may be indented to show a hierarchy

• module_item[page_url]

  Required for 'Page' type

  Suffix for the linked wiki page (e.g. 'front-page')

• module_item[external_url]

  Required for 'ExternalUrl' and 'ExternalTool' types

  External url that the item points to

• module_item[new_tab]

  Optional, only applies to 'ExternalTool' type

  Whether the external tool opens in a new tab

• module_item[completion_requirement][type]

  Optional

  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]

  Required for completion_requirement type 'min_score'

  minimum score required to complete

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'

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

  The name of the module item

• module_item[position]

  Optional

  The position of this item in the module (1-based)

• module_item[indent]

  Optional

  0-based indent level; module items may be indented to show a hierarchy

• module_item[external_url]

  Optional, only applies to 'ExternalUrl' type

  External url that the item points to

• module_item[new_tab]

  Optional, only applies to 'ExternalTool' type

  Whether the external tool opens in a new tab

• module_item[completion_requirement][type]

  Optional

  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]

  Required for completion_requirement type 'min_score'

  minimum score required to complete

• module_item[published]

  Optional

  Whether the module item is published and visible to students

• module_item[module_id]

  Optional

  Move this item to another module by specifying the target module id here. The target module must be in the same course.

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'

Delete module item ContextModuleItemsApiController#destroy

DELETE /api/v1/courses/:course_id/modules/:module_id/items/:id

Delete a module item

curl https://<canvas>/api/v1/courses/<course_id>/modules/<module_id>/items/<item_id> \
  -X Delete \
  -H 'Authorization: Bearer <token>'

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.

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

  The new outcome group title.

• description

  Optional

  The new outcome group description.

• vendor_guid

  Optional

  A custom GUID for the learning standard.

• parent_outcome_group_id

  Optional, Integer

  The id of the new parent outcome group.

curl 'http://<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 'http://<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>"

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.

curl 'http://<canvas>/api/v1/accounts/1/outcome_groups/2.json' \ 
     -X DELETE \ 
     -H "Authorization: Bearer <token>"

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.

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

  The title of the new outcome. Required if outcome_id is absent.

• description

  Optional

  The description of the new outcome.

• vendor_guid

  Optional

  A custom GUID for the learning standard.

• mastery_points

  Optional, Integer

  The mastery threshold for the embedded rubric criterion.

• ratings[][description]

  Optional

  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.

curl 'http://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes/1.json' \ 
     -X PUT \ 
     -H "Authorization: Bearer <token>"

curl 'http://<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 'http://<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>"

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.

curl 'http://<canvas>/api/v1/accounts/1/outcome_groups/1/outcomes/1.json' \ 
     -X DELETE \ 
     -H "Authorization: Bearer <token>"

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.

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

  Required

  The title of the new outcome group.

• description

  Optional

  The description of the new outcome group.

• vendor_guid

  Optional

  A custom GUID for the learning standard

curl 'http://<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 'http://<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>"

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

  Required, Integer

  The ID of the source outcome group.

curl 'http://<canvas>/api/v1/accounts/2/outcome_groups/3/import.json' \ 
     -X POST \ 
     -F 'source_outcome_group_id=2' \ 
     -H "Authorization: Bearer <token>"

Show an outcome OutcomesApiController#show

GET /api/v1/outcomes/:id

Returns the details of the outcome with the given id.

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

  The new outcome title.

• description

  Optional

  The new outcome description.

• vendor_guid

  Optional

  A custom GUID for the learning standard.

• mastery_points

  Optional, Integer

  The new mastery threshold for the embedded rubric criterion.

• ratings[][description]

  Optional

  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.

curl 'http://<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 'http://<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>"

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

  Sort results by this field: one of 'title', 'created_at', or 'updated_at'

• order

  optional

  The sorting order: 'asc' (default) or 'desc'

• search_term

  (optional) The partial title of the pages to match and return.

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/123/pages?sort=title&order=asc

Show page WikiPagesApiController#show

GET /api/v1/courses/:course_id/pages/:url

GET /api/v1/groups/:group_id/pages/:url

GET /api/v1/courses/:course_id/front_page

GET /api/v1/groups/:group_id/front_page

Retrieve the content of a wiki page

Request Parameters:

• url

  the unique identifier for a page.

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/123/pages/my-page-url

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

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]

  the title for the new page.

• wiki_page[body]

  the content for the new page.

• wiki_page[hide_from_students]

  boolean

  whether the page should be hidden from students.

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

• wiki_page[front_page]

  optional

  boolean

  set an unhidden page as the front page (if true)

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

Update page WikiPagesApiController#update

PUT /api/v1/courses/:course_id/pages/:url

PUT /api/v1/groups/:group_id/pages/:url

PUT /api/v1/courses/:course_id/front_page

PUT /api/v1/groups/:group_id/front_page

Update the title or contents of a wiki page

Request Parameters:

• url

  the unique identifier for a page.

• wiki_page[title]

  optional

  the new title for the page.

  NOTE: changing a page's title will change its url. The updated url will be returned in the result.

• wiki_page[body]

  optional

  the new content for the page.

• wiki_page[hide_from_students]

  optional

  boolean; whether the page should be hidden from students.

• wiki_page[notify_of_update]

  optional

  boolean

  notify participants that the wiki page has been changed.

• wiki_page[published]

  optional

  boolean

  whether the page is published (true) or draft state (false)

• wiki_page[front_page]

  optional

  boolean

  set an unhidden page as the front page (if true), or un-set it (if false)

curl -X PUT -H 'Authorization: Bearer <token>' \ 
https://<canvas>/api/v1/courses/123/pages/the-page-url?wiki_page[body]=Updated+body+text

curl -X PUT -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/front_page?wiki_page[body]=Updated+body+text

Delete page WikiPagesApiController#destroy

DELETE /api/v1/courses/:course_id/pages/:url

DELETE /api/v1/groups/:group_id/pages/:url

DELETE /api/v1/courses/:course_id/front_page

DELETE /api/v1/groups/:group_id/front_page

Delete a wiki page

Request Parameters:

• url

  the unique identifier for a page.

curl -X DELETE -H 'Authorization: Bearer <token>' \ 
https://<canvas>/api/v1/courses/123/pages/the-page-url

curl -X DELETE -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/courses/123/front_page

Query progress ProgressController#show

GET /api/v1/progress/:id

Return completion and status information about an asynchronous job

Create a quiz report 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]

  The type of report to be generated. One of "student_analysis", "item_analysis"

• quiz_report[includes_all_versions]

  Optional

  Whether the report should consider all submissions or only the most recent. Defaults to false, ignored for item_analysis.

Get a quiz report QuizReportsController#show

GET /api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id

Returns the data for a single quiz report.

List quizzes in a course QuizzesApiController#index

GET /api/v1/courses/:course_id/quizzes

Returns the list of Quizzes in this course.

Request Parameters:

• search_term

  (optional) The partial title of the quizzes to match and return.

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

Get a single quiz QuizzesApiController#show

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

Returns the quiz with the given id.

Create a quiz 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]

  null|"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]

  Boolean

  Only valid if hide_results=null If false, hides correct answers from students when quiz results are viewed. Defaults to true.

• quiz[allowed_attempts]

  Integer

  Number of times a student is allowed to take a quiz. Set to -1 for unlimited attempts. Defaults to 1.

• quiz[scoring_policy]

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

  Boolean

  If true, shows quiz to student one question at a time. Defaults to false.

• quiz[cant_go_back]

  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.

Edit a quiz 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

Delete a quiz QuizzesApiController#destroy

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

List roles RoleOverridesController#api_index

GET /api/v1/accounts/:account_id/roles

List the roles available to an account.

Request Parameters:

• account_id

  The id of the account to retrieve roles for.

• state[]

  Filter by role state. Accepted values are 'active' and 'inactive'. If this argument is omitted, only 'active' roles are returned.

Get a single role RoleOverridesController#show

GET /api/v1/accounts/:account_id/roles/:role

Retrieve information about a single role

Request Parameters:

• account_id

  The id of the account containing the role

• role

  The name and unique identifier for the 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

  Label and unique identifier for the role.

• base_role_type

  Optional

  Accepted values are 'AccountMembership', 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', and '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

• permissions[<X>][enabled]

  Optional

  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
  
  [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                     -- [sTAD ] 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

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