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.

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 listed in The Ruby on Rails documentation.

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

{
  "id": "1",
  "name": "New account name",
  "default_time_zone": "Mountain Time (US & Canada)",
  "parent_account_id": null,
  "root_account_id": null
}

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.

Request Parameters:

• include[]

  "assignments"

  Associations to include with the group.

API response field:

• id

  The unique identifier for the assignment group.

• name

  The name of the assignment group.

• position

  Integer

  The sorting order of this group in the

  groups for this context.

[
  {
    "position": 7,
    "name": "group2",
    "id": 1,
    "group_weight": 20,
    "assignments": [...],
    "rules" : {...}
  },
  {
    "position": 10,
    "name": "group1",
    "id": 2,
    "group_weight": 20,
    "assignments": [...],
    "rules" : {...}
  },
  {
    "position": 12,
    "name": "group3",
    "id": 3,
    "group_weight": 60,
    "assignments": [...],
    "rules" : {...}
  }
]

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

Request Parameters:

• include[]

  "submission"

  Associations to include with the

Get a single assignment AssignmentsApiController#show

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

Returns the assignment with the given id. assignment.

Request Parameters:

• include[]

  "submission"

  Associations to include with the

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.

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

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 listed in The Ruby on Rails documentation.

• 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 listed in The Ruby on Rails documentation.

• 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

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

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

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.

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

• 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

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

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.

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.

• 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

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

Request Parameters:

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

Search users CoursesController#search_users

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

Returns a list of users in this course that match a search term.

Request Parameters:

• search_term

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

  The same as the List Users API

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.

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

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

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

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.

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
• delayed_post_at

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

• 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, discusions 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.

• "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],
  "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".

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

• 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",
    "created_at": "2011-11-03T21:27:44Z" },
  {
    "id": 1014,
    "user_id": 7084,
    "user_name": "nobody@example.com",
    "message": "Older message",
    "read_state": "unread",
    "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".

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

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.

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.

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.

curl 'http://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/entries/<entry_id>/read.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.

[
 {
   "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 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 'http://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \ 
     -H "Authorization: Bearer <token>" \ 
     -F 'name=Public Example' \ 
     -F 'privacy_level=public'

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/folders/:id/files

Returns the paginated list of files for the folder.

curl 'https://<canvas>/api/v1/folders/<folder_id>/files' \ 
      -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 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

• create_group_count

  Optional

  Course Only

  automatically create groups, requires "enable_self_signup"

• split_group_count

  Optional

  Course Only

  split students into groups, not allowed with "enable_self_signup"

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

• create_group_count

  Optional

  Course Only

  automatically create groups, requires "enable_self_signup"

• split_group_count

  Optional

  Course Only

  creates groups and split students into groups, not allowed with "enable_self_signup"

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 your groups GroupsController#index

GET /api/v1/users/self/groups

Returns a list of active groups for the current user.

curl https://<canvas>/api/v1/users/self/groups \ 
     -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.

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.

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.

List group memberships GroupMembershipsController#index

GET /api/v1/groups/:group_id/memberships

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

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

Leave a group GroupMembershipsController#destroy

DELETE /api/v1/groups/:group_id/memberships/:membership_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>'

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

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

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

List module items ContextModulesApiController#list_module_items

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

List the items in a module

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

Show module item ContextModulesApiController#show_module_item

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

Get information about a single module item

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

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.

• 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 '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",
           "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.

• 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 '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",
           "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.

curl 'http://<canvas>/api/v1/accounts/1/outcome_groups/1/subgroups.json' \ 
     -X POST \ 
     -F 'title=Outcome Group Title' \ 
     -F 'description=Outcome group description' \ 
     -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"
         }' \ 
     -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.

• 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 '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",
           "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 WikiPagesController#api_index

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

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

Lists the wiki pages associated with a course or group.

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

Show page WikiPagesController#api_show

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

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

Retrieves the content of a wiki page.

Request Parameters:

• url

  the unique identifier for a page. Use 'front-page' to retrieve the front page of the wiki.

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

Query progress ProgressController#show

GET /api/v1/progress/:id

Return completion and status information about an asynchronous job

List quizzes in a course QuizzesApiController#index

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

Returns the list of Quizzes in this course.

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.

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

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

curl 'http://<canvas>/api/v1/accounts/<account_id>/roles.json' \ 
     -H "Authorization: Bearer <token>" \ 
     -F 'role=New Role' \ 
     -F 'permissions[read_course_content][explicit]=1' \ 
     -F 'permissions[read_course_content][enabled]=1' \ 
     -F 'permissions[read_course_list][locked]=1' \ 
     -F 'permissions[read_question_banks][explicit]=1' \ 
     -F 'permissions[read_question_banks][enabled]=0' \ 
     -F 'permissions[read_question_banks][locked]=1'

Deactivate a role RoleOverridesController#remove_role

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

Deactivates a custom role. This hides it in the user interface and prevents it from being assigned to new users. Existing users assigned to the role will continue to function with the same permissions they had previously. Built-in roles cannot be deactivated.

Request Parameters:

• role

  Label and unique identifier for the role.

Activate a role RoleOverridesController#activate_role

POST /api/v1/accounts/:account_id/roles/:role/activate

Re-activates an inactive role (allowing it to be assigned to new users)

Request Parameters:

• role

  Label and unique identifier for the role.

Update a role RoleOverridesController#update

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

Update permissions for an existing role.

Recognized roles are:

• TeacherEnrollment

• StudentEnrollment

• TaEnrollment

• ObserverEnrollment

• DesignerEnrollment

• AccountAdmin

• Any previously created custom role

Request Parameters:

• permissions[<X>][explicit]

  Optional

• permissions[<X>][enabled]

  Optional

  These arguments are described in the documentation for the add_role method.

curl https://<canvas>/api/v1/accounts/:account_id/roles/TaEnrollment \ 
  -X PUT \ 
  -H 'Authorization: Bearer <access_token>' \ 
  -F 'permissions[manage_groups][explicit]=1' \ 
  -F 'permissions[manage_groups][enabled]=1' \ 
  -F 'permissions[manage_groups][locked]=1' \ 
  -F 'permissions[send_messages][explicit]=1' \ 
  -F 'permissions[send_messages][enabled]=0'

Import SIS data SisImportsApiController#create

POST /api/v1/accounts/:account_id/sis_imports

Import SIS data into Canvas. Must be on a root account with SIS imports enabled.

For more information on the format that's expected here, please see the "SIS CSV" section in the API docs.

Request Parameters:

• import_type

  Choose the data format for reading SIS data. With a standard Canvas install, this option can only be 'instructure_csv', and if unprovided, will be assumed to be so. Can be part of the query string.

• attachment

  There are two ways to post SIS import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request.

  'attachment' is required for multipart/form-data style posts. Assumed to be SIS data from a file upload form field named 'attachment'.

  Examples:

  curl -F attachment=@<filename> -H "Authorization: Bearer <token>" \ 
      'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv'

  If you decide to do a raw post, you can skip the 'attachment' argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the 'extension' argument.

  Examples:

  curl -H 'Content-Type: application/octet-stream' --data-binary @<filename>.zip \ 
      -H "Authorization: Bearer <token>" \ 
      'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv&extension=zip'
  
  curl -H 'Content-Type: application/zip' --data-binary @<filename>.zip \ 
      -H "Authorization: Bearer <token>" \ 
      'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv'
  
  curl -H 'Content-Type: text/csv' --data-binary @<filename>.csv \ 
      -H "Authorization: Bearer <token>" \ 
      'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv'
  
  curl -H 'Content-Type: text/csv' --data-binary @<filename>.csv \ 
      -H "Authorization: Bearer <token>" \ 
      'https://<canvas>/api/v1/accounts/<account_id>/sis_imports.json?import_type=instructure_csv&batch_mode=1&batch_mode_term_id=15'

• extension

  Recommended for raw post request style imports. This field will be used to distinguish between zip, xml, csv, and other file format extensions that would usually be provided with the filename in the multipart post request scenario. If not provided, this value will be inferred from the Content-Type, falling back to zip-file format if all else fails.

• batch_mode

  "1"

  If set, this SIS import will be run in batch mode, deleting any data previously imported via SIS that is not present in this latest import. See the SIS CSV Format page for details.

• batch_mode_term_id

  Limit deletions to only this term, if batch mode is enabled.

• override_sis_stickiness

  "1"

  Many fields on records in Canvas can be marked "sticky," which means that when something changes in the UI apart from the SIS, that field gets "stuck." In this way, by default, SIS imports do not override UI changes. If this field is present, however, it will tell the SIS import to ignore "stickiness" and override all fields.

• add_sis_stickiness

  "1"

  This option, if present, will process all changes as if they were UI changes. This means that "stickiness" will be added to changed fields. This option is only processed if 'override_sis_stickiness' is also provided.

• clear_sis_stickiness

  "1"

  This option, if present, will clear "stickiness" from all fields touched by this import. Requires that 'override_sis_stickiness' is also provided. If 'add_sis_stickiness' is also provided, 'clear_sis_stickiness' will overrule the behavior of 'add_sis_stickiness'

Get SIS import status SisImportsApiController#show

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

Get the status of an already created SIS import.

Find recipients SearchController#recipients

GET /api/v1/conversations/find_recipients

GET /api/v1/search/recipients

Find valid recipients (users, courses and groups) that the current user can send messages to. The /api/v1/search/recipients path is the preferred endpoint, /api/v1/conversations/find_recipients is deprecated.

Pagination is supported.

Request Parameters:

• search

  Search terms used for matching users/courses/groups (e.g. "bob smith"). If multiple terms are given (separated via whitespace), only results matching all terms will be returned.

• context

  Limit the search to a particular course/group (e.g. "course_3" or "group_4").

• exclude[]

  Array of ids to exclude from the search. These may be user ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. exclude[]=1&exclude=2&exclude[]=course_3

• type

  "user"|"context"

  Limit the search just to users or contexts (groups/courses).

• user_id

  Integer

  Search for a specific user id. This ignores the other above parameters, and will never return more than one result.

• from_conversation_id

  Integer

  When searching by user_id, only users that could be normally messaged by this user will be returned. This parameter allows you to specify a conversation that will be referenced for a shared context -- if both the current user and the searched user are in the conversation, the user will be returned. This is used to start new side conversations.

• permissions[]

  Array of permission strings to be checked for each matched context (e.g. "send_messages"). This argument determines which permissions may be returned in the response; it won't prevent contexts from being returned if they don't grant the permission(s)

API response field:

• id

  The unique identifier for the user/context. For groups/courses, the id is prefixed by "group_"/"course_" respectively.

• name

  The name of the user/context

• avatar_url

  Avatar image url for the user/context

• type

  "context"|"course"|"section"|"group"|"user"|null

  Type of recipients to return, defaults to null (all). "context" encompasses "course", "section" and "group"

• types[]

  Array of recipient types to return (see type above), e.g. types[]=user&types=course

• user_count

  Only set for contexts, indicates number of messageable users

• common_courses

  Only set for users. Hash of course ids and enrollment types for each course to show what they share with this user

• common_groups

  Only set for users. Hash of group ids and enrollment types for each group to show what they share with this user

• permissions[]

  Only set for contexts. Mapping of requested permissions that the context grants the current user, e.g. { send_messages: true }

[
  {"id": "group_1", "name": "the group", "type": "context", "user_count": 3},
  {"id": 2, "name": "greg", "common_courses": {}, "common_groups": {"1": ["Member"]}}
]

List course sections SectionsController#index

GET /api/v1/courses/:course_id/sections

Returns the list of sections for this course.

Request Parameters:

• include[]

  optional, "students"

  Associations to include with the group.

• include[]

  optional, "avatar_url"

  Include the avatar URLs for students returned.

Create course section SectionsController#create

POST /api/v1/courses/:course_id/sections

Creates a new section for this course.

Request Parameters:

• course_section[name]

  String

  The name of the section

• course_section[sis_section_id]

  String, optional

  The sis ID of the section

• course_section[start_at]

  Datetime, optional

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

• course_section[end_at]

  Datetime, optional

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

Cross-list a Section SectionsController#crosslist

POST /api/v1/sections/:id/crosslist/:new_course_id

Move the Section to another course. The new course may be in a different account (department), but must belong to the same root account (institution).

De-cross-list a Section SectionsController#uncrosslist

DELETE /api/v1/sections/:id/crosslist

Undo cross-listing of a Section, returning it to its original course.

Edit a section SectionsController#update

PUT /api/v1/sections/:id

Modify an existing section. See the documentation for create API action.

Get section information SectionsController#show

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

GET /api/v1/sections/:id

Gets details about a specific section

Delete a section SectionsController#destroy

DELETE /api/v1/sections/:id

Delete an existing section. Returns the former Section.

Get Kaltura config ServicesApiController#show_kaltura_config

GET /api/v1/services/kaltura

Return the config information for the Kaltura plugin in json format.

API response field:

• enabled

  Enabled state of the Kaltura plugin

• domain

  Main domain of the Kaltura instance (This is the URL where the Kaltura API resides)

• resources_domain

  Kaltura URL for grabbing thumbnails and other resources

• rtmp_domain

  Hostname to be used for RTMP recording

• partner_id

  Partner ID used for communicating with the Kaltura instance

# For an enabled Kaltura plugin:
{
  'domain': 'kaltura.example.com',
  'enabled': true,
  'partner_id': '123456',
  'resource_domain': 'cdn.kaltura.example.com',
  'rtmp_domain': 'rtmp.example.com'
}

# For a disabled or unconfigured Kaltura plugin:
{
  'enabled': false
}

Start Kaltura session ServicesApiController#start_kaltura_session

POST /api/v1/services/kaltura_session

Start a new Kaltura session, so that new media can be recorded and uploaded to this Canvas instance's Kaltura instance.

API response field:

• ks

  The kaltura session id, for use in the kaltura v3 API. This can be used in the uploadtoken service, for instance, to upload a new media file into kaltura.

{
  'ks': '1e39ad505f30c4fa1af5752b51bd69fe'
}

Submit an assignment SubmissionsController#create

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

POST /api/v1/sections/:section_id/assignments/:assignment_id/submissions

Make a submission for an assignment. You must be enrolled as a student in the course/section to do this.

All online turn-in submission types are supported in this API. However, there are a few things that are not yet supported:

• Files can be submitted based on a file ID of a user or group file. However, there is no API yet for listing the user and group files, or uploading new files via the API. A file upload API is coming soon.

• Media comments can be submitted, however, there is no API yet for creating a media comment to submit.

• Integration with Google Docs is not yet supported.

Request Parameters:

• comment[text_comment]

  Include a textual comment with the submission.

• submission[submission_type]

  Required, "online_text_entry"|"online_url"|"online_upload"|"media_recording"

  The type of submission being made. The assignment submission_types must include this submission type as an allowed option, or the submission will be rejected with a 400 error.

  The submission_type given determines which of the following parameters is used. For instance, to submit a URL, submission must be set to "online_url", otherwise the submission parameter will be ignored.

• submission[body]

  Submit the assignment as an HTML document snippet. Note this HTML snippet will be sanitized using the same ruleset as a submission made from the Canvas web UI. The sanitized HTML will be returned in the response as the submission body. Requires a submission_type of "online_text_entry".

• submission[url]

  Submit the assignment as a URL. The URL scheme must be "http" or "https", no "ftp" or other URL schemes are allowed. If no scheme is given (e.g. "www.example.com") then "http" will be assumed. Requires a submission_type of "online_url".

• submission[file_ids][]

  Submit the assignment as a set of one or more previously uploaded files residing in the submitting user's files section (or the group's files section, for group assignments).

  To upload a new file to submit, see the submissions Upload a file API.

  Requires a submission_type of "online_upload".

• submission[media_comment_id]

  The media comment id to submit. Media comment ids can be submitted via this API, however, note that there is not yet an API to generate or list existing media comments, so this functionality is currently of limited use.

  Requires a submission_type of "media_recording".

• submission[media_comment_type]

  "audio"|"video"

  The type of media comment being submitted.

List assignment submissions SubmissionsApiController#index

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

GET /api/v1/sections/:section_id/assignments/:assignment_id/submissions

Get all existing submissions for an assignment.

Fields include:

assignment_id

The unique identifier for the assignment.

user_id

The id of the user who submitted the assignment.

grader_id

The id of the user who graded the assignment.

submitted_at

The timestamp when the assignment was submitted, if an actual submission has been made.

score

The raw score for the assignment submission.

attempt

If multiple submissions have been made, this is the attempt number.

body

The content of the submission, if it was submitted directly in a text field.

grade

The grade for the submission, translated into the assignment grading scheme (so a letter grade, for example).

grade_matches_current_submission

A boolean flag which is false if the student has re-submitted since the submission was last graded.

preview_url

Link to the URL in canvas where the submission can be previewed. This will require the user to log in.

submitted_at

Timestamp when the submission was made.

url

If the submission was made as a URL.

late

Whether the submission was made after the applicable due date.

Request Parameters:

• include[]

  "submission_history"|"submission_comments"|"rubric_assessment"|"assignment"

  Associations to include with the group.

List submissions for multiple assignments SubmissionsApiController#for_students

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

GET /api/v1/sections/:section_id/students/submissions

Get all existing submissions for a given set of students and assignments.

Request Parameters:

• student_ids[]

  List of student ids to return submissions for. At least one is required.

• assignment_ids[]

  List of assignments to return submissions for. If none are given, submissions for all assignments are returned.

• grouped

  If this argument is present, the response will be grouped by student, rather than a flat array of submissions.

• include[]

  "submission_history"|"submission_comments"|"rubric_assessment"|"assignment"|"total_scores"

  Associations to include with the group. `total_scores` requires the `grouped` argument.

# Without grouped:

[
  { "assignment_id": 100, grade: 5, "user_id": 1, ... },
  { "assignment_id": 101, grade: 6, "user_id": 2, ... }

# With grouped:

[
  {
    "user_id": 1,
    "submissions": [
      { "assignment_id": 100, grade: 5, ... },
      { "assignment_id": 101, grade: 6, ... }
    ]
  }
]

Get a single submission SubmissionsApiController#show

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

GET /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:id

Get a single submission, based on user id.

Request Parameters:

• include[]

  "submission_history"|"submission_comments"|"rubric_assessment"

  Associations to include with the group.

Upload a file SubmissionsApiController#create_file

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/files

POST /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:user_id/files

Upload a file to a submission.

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

The final step of the file upload workflow will return the attachment data, including the new file id. The caller can then POST to submit the online_upload assignment with these file ids.

Grade or comment on a submission SubmissionsApiController#update

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

PUT /api/v1/sections/:section_id/assignments/:assignment_id/submissions/:id

Comment on and/or update the grading for a student's assignment submission. If any submission or rubric_assessment arguments are provided, the user must have permission to manage grades in the appropriate context (course or section).

Request Parameters:

• comment[text_comment]

  Add a textual comment to the submission.

• comment[group_comment]

  Boolean

  Whether or not this comment should be sent to the entire group (defaults to false). Ignored if this is not a group assignment or if no text_comment is provided.

• comment[media_comment_id]

  Add an audio/video comment to the submission. Media comments can be added via this API, however, note that there is not yet an API to generate or list existing media comments, so this functionality is currently of limited use.

• comment[media_comment_type]

  "audio"|"video"

  The type of media comment being added.

• submission[posted_grade]

  Assign a score to the submission, updating both the "score" and "grade" fields on the submission record. This parameter can be passed in a few different formats:

  points

  A floating point or integral value, such as "13.5". The grade will be interpreted directly as the score of the assignment. Values above assignment.points_possible are allowed, for awarding extra credit.

  percentage

  A floating point value appended with a percent sign, such as "40%". The grade will be interpreted as a percentage score on the assignment, where 100% == assignment.points_possible. Values above 100% are allowed, for awarding extra credit.

  letter grade

  A letter grade, following the assignment's defined letter grading scheme. For example, "A-". The resulting score will be the high end of the defined range for the letter grade. For instance, if "B" is defined as 86% to 84%, a letter grade of "B" will be worth 86%. The letter grade will be rejected if the assignment does not have a defined letter grading scheme. For more fine-grained control of scores, pass in points or percentage rather than the letter grade.

  "pass/complete/fail/incomplete"

  A string value of "pass" or "complete" will give a score of 100%. "fail" or "incomplete" will give a score of 0.

  Note that assignments with grading_type of "pass_fail" can only be assigned a score of 0 or assignment.points_possible, nothing inbetween. If a posted_grade in the "points" or "percentage" format is sent, the grade will only be accepted if the grade equals one of those two values.

• rubric_assessment

  Assign a rubric assessment to this assignment submission. The sub-parameters here depend on the rubric for the assignment. The general format is, for each row in the rubric:

  rubric_assessment[points]

  The points awarded for this row.

  rubric_assessment[comments]

  Comments to add for this row.

  For example, if the assignment rubric is (in JSON format):

  [
    {
      'id': 'crit1',
      'points': 10,
      'description': 'Criterion 1',
      'ratings':
      [
        { 'description': 'Good', 'points': 10 },
        { 'description': 'Poor', 'points': 3 }
      ]
    },
    {
      'id': 'crit2',
      'points': 5,
      'description': 'Criterion 2',
      'ratings':
      [
        { 'description': 'Complete', 'points': 5 },
        { 'description': 'Incomplete', 'points': 0 }
      ]
    }
  ]

  Then a possible set of values for rubric_assessment would be:

  rubric_assessment[crit1][points]=3&rubric_assessment[crit2][points]=5&rubric_assessment[crit2][comments]=Well%20Done.

List available tabs for a course or group TabsController#index

GET /api/v1/courses/:course_id/tabs

GET /api/v1/groups/:group_id/tabs

Returns a list of navigation tabs available in the current context.

(Only has effect for courses, not groups)

Request Parameters:

• include[]

  "external"

  Optionally include external tool tabs in the returned list of tabs

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/courses/<course_id>/tabs\?include\="external"

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

[
  {
    "html_url": "/courses/1",
    "id": "home",
    "label": "Home",
    "type": "internal"
  },
  {
    "html_url": "/courses/1/external_tools/4",
    "id": "context_external_tool_4",
    "label": "WordPress",
    "type": "external"
  },
  {
    "html_url": "/courses/1/grades",
    "id": "grades",
    "label": "Grades",
    "type": "internal"
  }
]

List users UsersController#index

GET /api/v1/accounts/:account_id/users

Retrieve the list of users associated with this account.

List the activity stream UsersController#activity_stream

GET /api/v1/users/self/activity_stream

GET /api/v1/users/activity_stream

Returns the current user's global activity stream, paginated.

There are many types of objects that can be returned in the activity stream. All object types have the same basic set of shared attributes:

{
  'created_at': '2011-07-13T09:12:00Z',
  'updated_at': '2011-07-25T08:52:41Z',
  'id': 1234,
  'title': 'Stream Item Subject',
  'message': 'This is the body text of the activity stream item. It is plain-text, and can be multiple paragraphs.',
  'type': 'DiscussionTopic|Conversation|Message|Submission|Conference|Collaboration|...',
  'context_type': 'course', // course|group
  'course_id': 1,
  'group_id': null,
  'html_url': "http://..." // URL to the Canvas web UI for this stream item
}

In addition, each item type has its own set of attributes available.

DiscussionTopic:

{
  'type': 'DiscussionTopic',
  'discussion_topic_id': 1234,
  'total_root_discussion_entries': 5,
  'require_initial_post': true,
  'user_has_posted': true,
  'root_discussion_entries': {
    ...
  }
}

For DiscussionTopic, the message is truncated at 4kb.

Announcement:

{
  'type': 'Announcement',
  'announcement_id': 1234,
  'total_root_discussion_entries': 5,
  'require_initial_post': true,
  'user_has_posted': null,
  'root_discussion_entries': {
    ...
  }
}

For Announcement, the message is truncated at 4kb.

Conversation:

{
  'type': 'Conversation',
  'conversation_id': 1234,
  'private': false,
  'participant_count': 3,
}

Message:

{
  'type': 'Message',
  'message_id': 1234,
  'notification_category': 'Assignment Graded'
}

Submission:

Returns an Submission with its Course and Assignment data.

Conference:

{
  'type': 'Conference',
  'web_conference_id': 1234
}

Collaboration:

{
  'type': 'Collaboration',
  'collaboration_id': 1234
}

CollectionItem:

{
  'type': 'CollectionItem',
  'collection_item' { ... full CollectionItem data ... }
}

List the TODO items UsersController#todo_items

GET /api/v1/users/self/todo

Returns the current user's list of todo items, as seen on the user dashboard.

There is a limit to the number of items returned.

The `ignore` and `ignore_permanently` URLs can be used to update the user's preferences on what items will be displayed. Performing a DELETE request against the `ignore` URL will hide that item from future todo item requests, until the item changes. Performing a DELETE request against the `ignore_permanently` URL will hide that item forever.

[
  {
    'type': 'grading',        // an assignment that needs grading
    'assignment': { .. assignment object .. },
    'ignore': '.. url ..',
    'ignore_permanently': '.. url ..',
    'html_url': '.. url ..',
    'needs_grading_count': 3, // number of submissions that need grading
    'context_type': 'course', // course|group
    'course_id': 1,
    'group_id': null,
  },
  {
    'type' => 'submitting',   // an assignment that needs submitting soon
    'assignment' => { .. assignment object .. },
    'ignore' => '.. url ..',
    'ignore_permanently' => '.. url ..',
    'html_url': '.. url ..',
    'context_type': 'course',
    'course_id': 1,
  }
]

Upload a file UsersController#create_file

POST /api/v1/users/:user_id/files

Upload a file to the user's personal files section.

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

Note that typically users will only be able to upload files to their own files section. Passing a user_id of self is an easy shortcut to specify the current user.

Create a user UsersController#create

POST /api/v1/accounts/:account_id/users

Create and return a new user and pseudonym for an account.

Request Parameters:

• user[name]

  Optional

  The full name of the user. This name will be used by teacher for grading.

• user[short_name]

  Optional

  User's name as it will be displayed in discussions, messages, and comments.

• user[sortable_name]

  Optional

  User's name as used to sort alphabetically in lists.

• user[time_zone]

  Optional

  The time zone for the user. Allowed time zones are listed in The Ruby on Rails documentation.

• user[locale]

  Optional

  The user's preferred language as a two-letter ISO 639-1 code. Current supported languages are English ("en") and Spanish ("es").

• user[birthdate]

  Optional

  The user's birth date.

• pseudonym[unique_id]

  User's login ID.

• pseudonym[password]

  Optional

  User's password.

• pseudonym[sis_user_id]

  Optional

  Integer

  SIS ID for the user's account. To set this parameter, the caller must be able to manage SIS permissions.

• pseudonym[send_confirmation]

  Optional, 0|1

  Integer

  Send user notification of account creation if set to 1.

Edit a user UsersController#update

PUT /api/v1/users/:id

Modify an existing user. To modify a user's login, see the documentation for logins.

Request Parameters:

• user[name]

  Optional

  The full name of the user. This name will be used by teacher for grading.

• user[short_name]

  Optional

  User's name as it will be displayed in discussions, messages, and comments.

• user[sortable_name]

  Optional

  User's name as used to sort alphabetically in lists.

• user[time_zone]

  Optional

  The time zone for the user. Allowed time zones are listed in The Ruby on Rails documentation.

• user[locale]

  Optional

  The user's preferred language as a two-letter ISO 639-1 code. Current supported languages are English ("en") and Spanish ("es").

• user[avatar][token]

  Optional

  A unique representation of the avatar record to assign as the user's current avatar. This token can be obtained from the user avatars endpoint. This supersedes the user[url] argument, and if both are included the url will be ignored. Note: this is an internal representation and is subject to change without notice. It should be consumed with this api endpoint and used in the user update endpoint, and should not be constructed by the client.

• user[avatar][url]

  Optional

  To set the user's avatar to point to an external url, do not include a token and instead pass the url here. Warning: For maximum compatibility, please use 128 px square images.

curl 'http://<canvas>/api/v1/users/133.json' \ 
     -X PUT \ 
     -F 'user[name]=Sheldon Cooper' \ 
     -F 'user[short_name]=Shelly' \ 
     -F 'user[time_zone]=Pacific Time (US & Canada)' \ 
     -F 'user[avatar][token]=<opaque_token>' \ 
     -H "Authorization: Bearer <token>"

Delete a user UsersController#destroy

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

Delete a user record from Canvas.

WARNING: This API will allow a user to delete themselves. If you do this, you won't be able to make API calls or log into Canvas.

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

Follow a user UsersController#follow

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

PUT /api/v1/users/:user_id/followers/self

Follow this user. If the current user is already following the target user, nothing happens. The target user must have a public profile in order to follow it.

On success, returns the User object. Responds with a 401 if the user doesn't have permission to follow the target user, or a 400 if the user can't follow the target user (if the user and target user are the same, for example).

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

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

Un-follow a user UsersController#unfollow

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

DELETE /api/v1/users/:user_id/followers/self

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

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

Get user profile ProfileController#settings

GET /api/v1/users/:user_id/profile

Returns user profile data, including user id, name, and profile pic.

When requesting the profile for the user accessing the API, the user's calendar feed URL will be returned as well.

{
  'id': 1234,
  'name': 'Sample User',
  'short_name': 'Sample User'
  'sortable_name': 'user, sample',
  'primary_email': 'sample_user@example.com',
  'login_id': 'sample_user@example.com',
  'sis_user_id': 'sis1',
  'sis_login_id': 'sis1-login',
  // The avatar_url can change over time, so we recommend not caching it for more than a few hours
  'avatar_url': '..url..',
  'calendar': { 'ics' => '..url..' }
}

List avatar options ProfileController#profile_pics

GET /api/v1/users/:user_id/avatars

Retrieve the possible user avatar options that can be set with the user update endpoint. The response will be an array of avatar records. If the 'type' field is 'attachment', the record will include all the normal attachment json fields; otherwise it will include only the 'url' and 'display_name' fields. Additionally, all records will include a 'type' field and a 'token' field. The following explains each field in more detail

type

"gravatar"|"attachment"|"no_pic"

The type of avatar record, for categorization purposes.

url

The url of the avatar

token

A unique representation of the avatar record which can be used to set the avatar with the user update endpoint. Note: this is an internal representation and is subject to change without notice. It should be consumed with this api endpoint and used in the user update endpoint, and should not be constructed by the client.

display_name

A textual description of the avatar record

id

'attachment' type only

the internal id of the attachment

content-type

'attachment' type only

the content-type of the attachment

filename

'attachment' type only

the filename of the attachment

size

'attachment' type only

the size of the attachment

curl 'http://<canvas>/api/v1/users/1/avatars.json' \ 
     -H "Authorization: Bearer <token>"

[
  {
    "type":"gravatar",
    "url":"https://secure.gravatar.com/avatar/2284...",
    "token":<opaque_token>,
    "display_name":"gravatar pic"
  },
  {
    "type":"attachment",
    "url":"https://<canvas>/images/thumbnails/12/gpLWJ...",
    "token":<opaque_token>,
    "display_name":"profile.jpg",
    "id":12,
    "content-type":"image/jpeg",
    "filename":"profile.jpg",
    "size":32649
  },
  {
    "type":"no_pic",
    "url":"https://<canvas>/images/dotted_pic.png",
    "token":<opaque_token>,
    "display_name":"no pic"
  }
]

List user page views PageViewsController#index

GET /api/v1/users/:user_id/page_views

Return the user's page view history in json format, similar to the available CSV download. Pagination is used as described in API basics section. Page views are returned in descending order, newest to oldest.

API response field:

• interaction_seconds

  The number of seconds the user actively interacted with the page. This is a best guess, using heuristics such as browser input events.

• url

  The full canvas URL of the page view.

• user_agent

  The browser identifier or other user agent that was used to make the request.

• controller

  The Rails controller that processed the request.

• action

  The action in the Rails controller that processed the request.

• context_type

  The type of "context" of the request, e.g. Account or Course.