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|AssessmentRequest...',
  'read_state': false,
  'context_type': 'course', // course|group
  'course_id': 1,
  'group_id': null,
  'html_url': "http://..." // URL to the Canvas web UI for this stream item
}

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

DiscussionTopic:

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

For DiscussionTopic, the message is truncated at 4kb.

Announcement:

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

For Announcement, the message is truncated at 4kb.

Conversation:

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

Message:

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

Submission:

Returns an Submission with its Course and Assignment data.

Conference:

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

Collaboration:

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

AssessmentRequest:

{
  'type': 'AssessmentRequest',
  'assessment_request_id': 1234
}

Request Parameters:

Activity stream summary UsersController#activity_stream_summary

GET /api/v1/users/self/activity_stream/summary

Returns a summary of the current user’s global activity stream.

Request Parameters:

[
  {
    "type": "DiscussionTopic",
    "unread_count": 2,
    "count": 7
  },
  {
    "type": "Conversation",
    "unread_count": 0,
    "count": 3
  }
]

List the TODO items UsersController#todo_items

GET /api/v1/users/self/todo

A paginated list of the current user’s list of todo items.

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.

Request Parameters:

[
  {
    '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,
  },
  {
    'type' => 'submitting',   // a quiz that needs submitting soon
    'quiz' => { .. quiz object .. },
    'ignore' => '.. url ..',
    'ignore_permanently' => '.. url ..',
    'html_url': '.. url ..',
    'context_type': 'course',
    'course_id': 1,
  },
]

List counts for todo items UsersController#todo_item_count

GET /api/v1/users/self/todo_item_count

Counts of different todo items such as the number of assignments needing grading as well as the number of assignments needing submitting.

There is a limit to the number of todo items this endpoint will count. It will only look at the first 100 todo items for the user. If the user has more than 100 todo items this count may not be reliable. The largest reliable number for both counts is 100.

Request Parameters:

{
  needs_grading_count: 32,
  assignments_needing_submitting: 10
}

List upcoming assignments, calendar events UsersController#upcoming_events

GET /api/v1/users/self/upcoming_events

A paginated list of the current user’s upcoming events.

[
  {
    "id"=>597,
    "title"=>"Upcoming Course Event",
    "description"=>"Attendance is correlated with passing!",
    "start_at"=>"2013-04-27T14:33:14Z",
    "end_at"=>"2013-04-27T14:33:14Z",
    "location_name"=>"Red brick house",
    "location_address"=>"110 Top of the Hill Dr.",
    "all_day"=>false,
    "all_day_date"=>nil,
    "created_at"=>"2013-04-26T14:33:14Z",
    "updated_at"=>"2013-04-26T14:33:14Z",
    "workflow_state"=>"active",
    "context_code"=>"course_12938",
    "child_events_count"=>0,
    "child_events"=>[],
    "parent_event_id"=>nil,
    "hidden"=>false,
    "url"=>"http://www.example.com/api/v1/calendar_events/597",
    "html_url"=>"http://www.example.com/calendar?event_id=597&include_contexts=course_12938"
  },
  {
    "id"=>"assignment_9729",
    "title"=>"Upcoming Assignment",
    "description"=>nil,
    "start_at"=>"2013-04-28T14:47:32Z",
    "end_at"=>"2013-04-28T14:47:32Z",
    "all_day"=>false,
    "all_day_date"=>"2013-04-28",
    "created_at"=>"2013-04-26T14:47:32Z",
    "updated_at"=>"2013-04-26T14:47:32Z",
    "workflow_state"=>"published",
    "context_code"=>"course_12942",
    "assignment"=>{
      "id"=>9729,
      "name"=>"Upcoming Assignment",
      "description"=>nil,
      "points_possible"=>10,
      "due_at"=>"2013-04-28T14:47:32Z",
      "assignment_group_id"=>2439,
      "automatic_peer_reviews"=>false,
      "grade_group_students_individually"=>nil,
      "grading_standard_id"=>nil,
      "grading_type"=>"points",
      "group_category_id"=>nil,
      "lock_at"=>nil,
      "peer_reviews"=>false,
      "position"=>1,
      "unlock_at"=>nil,
      "course_id"=>12942,
      "submission_types"=>["none"],
      "needs_grading_count"=>0,
      "html_url"=>"http://www.example.com/courses/12942/assignments/9729"
    },
    "url"=>"http://www.example.com/api/v1/calendar_events/assignment_9729",
    "html_url"=>"http://www.example.com/courses/12942/assignments/9729"
  }
]

List Missing Submissions UsersController#missing_submissions

GET /api/v1/users/:user_id/missing_submissions

A paginated list of past-due assignments for which the student does not have a submission. The user sending the request must either be the student, an admin or a parent observer using the parent app

Request Parameters:

Hide a stream item UsersController#ignore_stream_item

DELETE /api/v1/users/self/activity_stream/:id

Hide the given stream item.

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

{
  "hidden": true
}

Hide all stream items UsersController#ignore_all_stream_items

DELETE /api/v1/users/self/activity_stream

Hide all stream items for the user

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

{
  "hidden": true
}

Upload a file UsersController#create_file

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

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

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

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

Show user details UsersController#api_show

GET /api/v1/users/:id

Shows details for user.

Also includes an attribute “permissions”, a non-comprehensive list of permissions for the user. Example:

"permissions": {
 "can_update_name": true, // Whether the user can update their name.
 "can_update_avatar": false, // Whether the user can update their avatar.
 "limit_parent_app_web_access": false // Whether the user can interact with Canvas web from the Canvas Parent app.
}

Request Parameters:

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

Create a user UsersController#create

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

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

DEPRECATED (for self-registration only)

If you don’t have the “Modify

login details for users“ permission, but self-registration is enabled on the account, you can still use this endpoint to register new users. Certain fields will be required, and others will be ignored (see below).

Request Parameters:

[DEPRECATED] Self register a user UsersController#create_self_registered_user

POST /api/v1/accounts/:account_id/self_registration

Self register and return a new user and pseudonym for an account.

If self-registration is enabled on the account, you can use this endpoint to self register new users.

Request Parameters:

Update user settings. UsersController#settings

GET /api/v1/users/:id/settings

PUT /api/v1/users/:id/settings

Update an existing user’s settings.

Request Parameters:

curl 'https://<canvas>/api/v1/users/<user_id>/settings \
  -X PUT \
  -F 'manual_mark_as_read=true'
  -H 'Authorization: Bearer <token>'

Get custom colors UsersController#get_custom_colors

GET /api/v1/users/:id/colors

Returns all custom colors that have been saved for a user.

curl 'https://<canvas>/api/v1/users/<user_id>/colors/ \
  -X GET \
  -H 'Authorization: Bearer <token>'

{
  "custom_colors": {
    "course_42": "#abc123",
    "course_88": "#123abc"
  }
}

Get custom color UsersController#get_custom_color

GET /api/v1/users/:id/colors/:asset_string

Returns the custom colors that have been saved for a user for a given context.

The asset_string parameter should be in the format ‘context_id’, for example ‘course_42’.

curl 'https://<canvas>/api/v1/users/<user_id>/colors/<asset_string> \
  -X GET \
  -H 'Authorization: Bearer <token>'

{
  "hexcode": "#abc123"
}

Update custom color UsersController#set_custom_color

PUT /api/v1/users/:id/colors/:asset_string

Updates a custom color for a user for a given context. This allows colors for the calendar and elsewhere to be customized on a user basis.

The asset string parameter should be in the format ‘context_id’, for example ‘course_42’

Request Parameters:

curl 'https://<canvas>/api/v1/users/<user_id>/colors/<asset_string> \
  -X PUT \
  -F 'hexcode=fffeee'
  -H 'Authorization: Bearer <token>'

{
  "hexcode": "#abc123"
}

Get dashboard positions UsersController#get_dashboard_positions

GET /api/v1/users/:id/dashboard_positions

Returns all dashboard positions that have been saved for a user.

curl 'https://<canvas>/api/v1/users/<user_id>/dashboard_positions/ \
  -X GET \
  -H 'Authorization: Bearer <token>'

{
  "dashboard_positions": {
    "course_42": 2,
    "course_88": 1
  }
}

Update dashboard positions UsersController#set_dashboard_positions

PUT /api/v1/users/:id/dashboard_positions

Updates the dashboard positions for a user for a given context. This allows positions for the dashboard cards and elsewhere to be customized on a per user basis.

The asset string parameter should be in the format ‘context_id’, for example ‘course_42’

curl 'https://<canvas>/api/v1/users/<user_id>/dashboard_positions/ \
  -X PUT \
  -F 'dashboard_positions[course_42]=1' \
  -F 'dashboard_positions[course_53]=2' \
  -F 'dashboard_positions[course_10]=3' \
  -H 'Authorization: Bearer <token>'

{
  "dashboard_positions": {
    "course_10": 3,
    "course_42": 1,
    "course_53": 2
  }
}

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:

curl 'https://<canvas>/api/v1/users/133' \
     -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>"

Terminate all user sessions UsersController#terminate_sessions

DELETE /api/v1/users/:id/sessions

Terminates all sessions for a user. This includes all browser-based sessions and all access tokens, including manually generated ones. The user can immediately re-authenticate to access Canvas again if they have the current credentials. All integrations will need to be re-authorized.

Log users out of all mobile apps UsersController#expire_mobile_sessions

DELETE /api/v1/users/mobile_sessions

DELETE /api/v1/users/:id/mobile_sessions

Permanently expires any active mobile sessions, forcing them to re-authorize.

The route that takes a user id will expire mobile sessions for that user. The route that doesn’t take a user id will expire mobile sessions for all users in the institution.

Merge user into another user UsersController#merge_into

PUT /api/v1/users/:id/merge_into/:destination_user_id

PUT /api/v1/users/:id/merge_into/accounts/:destination_account_id/users/:destination_user_id

Merge a user into another user. To merge users, the caller must have permissions to manage both users. This should be considered irreversible. This will delete the user and move all the data into the destination user.

User merge details and caveats: The from_user is the user that was deleted in the user_merge process. The destination_user is the user that remains, that is being split.

Avatars: When both users have avatars, only the destination_users avatar will remain. When one user has an avatar, will it will end up on the destination_user.

Terms of Use: If either user has accepted terms of use, it will be be left as accepted.

Communication Channels: All unique communication channels moved to the destination_user. All notification preferences are moved to the destination_user.

Enrollments: All unique enrollments are moved to the destination_user. When there is an enrollment that would end up making it so that a user would be observing themselves, the enrollment is not moved over. Everything that is tied to the from_user at the course level relating to the enrollment is also moved to the destination_user.

Submissions: All submissions are moved to the destination_user. If there are enrollments for both users in the same course, we prefer submissions that have grades then submissions that have work in them, and if there are no grades or no work, they are not moved.

Other notes: Access Tokens are moved on merge. Conversations are moved on merge. Favorites are moved on merge. Courses will commonly use LTI tools. LTI tools reference the user with IDs that are stored on a user object. Merging users deletes one user and moves all records from the deleted user to the destination_user. These IDs are kept for all enrollments, group_membership, and account_users for the from_user at the time of the merge. When the destination_user launches an LTI tool from a course that used to be the from_user’s, it doesn’t appear as a new user to the tool provider. Instead it will send the stored ids. The destination_user’s LTI IDs remain as they were for the courses that they originally had. Future enrollments for the destination_user will use the IDs that are on the destination_user object. LTI IDs that are kept and tracked per context include lti_context_id, lti_id and uuid. APIs that return the LTI ids will return the one for the context that it is called for, except for the user uuid. The user UUID will display the destination_users uuid, and when getting the uuid from an api that is in a context that was recorded from a merge event, an additional attribute is added as past_uuid.

When finding users by SIS ids in different accounts the destination_account_id is required.

The account can also be identified by passing the domain in destination_account_id.

curl https://<canvas>/api/v1/users/<user_id>/merge_into/<destination_user_id> \
     -X PUT \
     -H 'Authorization: Bearer <token>'

curl https://<canvas>/api/v1/users/<user_id>/merge_into/accounts/<destination_account_id>/users/<destination_user_id> \
     -X PUT \
     -H 'Authorization: Bearer <token>'

Split merged users into separate users UsersController#split

POST /api/v1/users/:id/split

Merged users cannot be fully restored to their previous state, but this will attempt to split as much as possible to the previous state. To split a merged user, the caller must have permissions to manage all of the users logins. If there are multiple users that have been merged into one user it will split each merge into a separate user. A split can only happen within 180 days of a user merge. A user merge deletes the previous user and may be permanently deleted. In this scenario we create a new user object and proceed to move as much as possible to the new user. The user object will not have preserved the name or settings from the previous user. Some items may have been deleted during a user_merge that cannot be restored, and/or the data has become stale because of other changes to the objects since the time of the user_merge.

Split users details and caveats:

The from_user is the user that was deleted in the user_merge process. The destination_user is the user that remains, that is being split.

Avatars: When both users had avatars, both will be remain. When from_user had an avatar and destination_user did not have an avatar, the destination_user’s avatar will be deleted if it still matches what was there are the time of the merge. If the destination_user’s avatar was changed at anytime after the merge, it will remain on the destination user. If the from_user had an avatar it will be there after split.

Terms of Use: If from_user had not accepted terms of use, they will be prompted again to accept terms of use after the split. If the destination_user had not accepted terms of use, hey will be prompted again to accept terms of use after the split. If neither user had accepted the terms of use, but since the time of the merge had accepted, both will be prompted to accept terms of use. If both had accepted terms of use, this will remain.

Communication Channels: All communication channels are restored to what they were prior to the merge. If a communication channel was added after the merge, it will remain on the destination_user. Notification preferences remain with the communication channels.

Enrollments: All enrollments from the time of the merge will be moved back to where they were. Enrollments created since the time of the merge that were created by sis_import will go to the user that owns that sis_id used for the import. Other new enrollments will remain on the destination_user. Everything that is tied to the destination_user at the course level relating to an enrollment is moved to the from_user. When both users are in the same course prior to merge this can cause some unexpected items to move.

Submissions: Unlike other items tied to a course, submissions are explicitly recorded to avoid problems with grades. All submissions were moved are restored to the spot prior to merge. All submission that were created in a course that was moved in enrollments are moved over to the from_user.

Other notes: Access Tokens are moved back on split. Conversations are moved back on split. Favorites that existing at the time of merge are moved back on split. LTI ids are restored to how they were prior to merge.

curl https://<canvas>/api/v1/users/<user_id>/split \
     -X POST \
     -H 'Authorization: Bearer <token>'

Get a Pandata Events jwt token and its expiration date UsersController#pandata_events_token

POST /api/v1/users/self/pandata_events_token

Returns a jwt auth and props token that can be used to send events to Pandata.

NOTE: This is currently only available to the mobile developer keys.

Request Parameters:

curl https://<canvas>/api/v1/users/self/pandata_events_token \
     -X POST \
     -H 'Authorization: Bearer <token>'
     -F 'app_key=MOBILE_APPS_KEY' \

{
  "url": "https://example.com/pandata/events"
  "auth_token": "wek23klsdnsoieioeoi3of9deeo8r8eo8fdn",
  "props_token": "paowinefopwienpfiownepfiownepfownef",
  "expires_at": 1521667783000,
}

Get a users most recently graded submissions UsersController#user_graded_submissions

GET /api/v1/users/:id/graded_submissions

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 and LTI user id will be returned as well.

List avatar options ProfileController#profile_pics

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

A paginated list of 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 'https://<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":<url to fetch thumbnail of attachment>,
    "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 a paginated list of the user’s page view history in json format, similar to the available CSV download. Page views are returned in descending order, newest to oldest.

Request Parameters:

Store custom data CustomDataController#set_data

PUT /api/v1/users/:user_id/custom_data(/*scope)

Store arbitrary user data as JSON.

Arbitrary JSON data can be stored for a User. A typical scenario would be an external site/service that registers users in Canvas and wants to capture additional info about them. The part of the URL that follows /custom_data/ defines the scope of the request, and it reflects the structure of the JSON data to be stored or retrieved.

The value self may be used for user_id to store data associated with the calling user. In order to access another user’s custom data, you must be an account administrator with permission to manage users.

A namespace parameter, ns, is used to prevent custom_data collisions between different apps. This parameter is required for all custom_data requests.

A request with Content-Type multipart/form-data or Content-Type application/x-www-form-urlencoded can only be used to store strings.

Example PUT with multipart/form-data data:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/telephone' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data=555-1234' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "555-1234"
}

Subscopes (or, generated scopes) can also be specified by passing values to data[subscope].

Example PUT specifying subscopes:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/body/measurements' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data[waist]=32in' \
  -F 'data[inseam]=34in' \
  -F 'data[chest]=40in' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "chest": "40in",
    "waist": "32in",
    "inseam": "34in"
  }
}

Following such a request, subsets of the stored data to be retrieved directly from a subscope.

Example GET from a generated scope

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/body/measurements/chest' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "40in"
}

If you want to store more than just strings (i.e. numbers, arrays, hashes, true, false, and/or null), you must make a request with Content-Type application/json as in the following example.

Example PUT with JSON data:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{
        "ns": "com.my-organization.canvas-app",
        "data": {
          "a-number": 6.02e23,
          "a-bool": true,
          "a-string": "true",
          "a-hash": {"a": {"b": "ohai"}},
          "an-array": [1, "two", null, false]
        }
      }' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "a-number": 6.02e+23,
    "a-bool": true,
    "a-string": "true",
    "a-hash": {
      "a": {
        "b": "ohai"
      }
    },
    "an-array": [1, "two", null, false]
  }
}

If the data is an Object (as it is in the above example), then subsets of the data can be accessed by including the object’s (possibly nested) keys in the scope of a GET request.

Example GET with a generated scope:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/a-hash/a/b' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "ohai"
}

On success, this endpoint returns an object containing the data that was stored.

Responds with status code 200 if the scope already contained data, and it was overwritten by the data specified in the request.

Responds with status code 201 if the scope was previously empty, and the data specified in the request was successfully stored there.

Responds with status code 400 if the namespace parameter, ns, is missing or invalid, or if the data parameter is missing.

Responds with status code 409 if the requested scope caused a conflict and data was not stored. This happens when storing data at the requested scope would cause data at an outer scope to be lost. e.g., if /custom_data was {“fashion_app”: {“hair”: “blonde”}}, but you tried to ‘PUT /custom_data/fashion_app/hair/style -F data=buzz`, then for the request to succeed,the value of /custom_data/fashion_app/hair would have to become a hash, and its old string value would be lost. In this situation, an error object is returned with the following format:

{
  "message": "write conflict for custom_data hash",
  "conflict_scope": "fashion_app/hair",
  "type_at_conflict": "String",
  "value_at_conflict": "blonde"
}

Request Parameters:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/food_app' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data[weight]=81kg' \
  -F 'data[favorites][meat]=pork belly' \
  -F 'data[favorites][dessert]=pistachio ice cream' \
  -H 'Authorization: Bearer <token>'

{
  "data": {
    "weight": "81kg",
    "favorites": {
      "meat": "pork belly",
      "dessert": "pistachio ice cream"
    }
  }
}

Load custom data CustomDataController#get_data

GET /api/v1/users/:user_id/custom_data(/*scope)

Load custom user data.

Arbitrary JSON data can be stored for a User. This API call retrieves that data for a (optional) given scope. See Store Custom Data for details and examples.

On success, this endpoint returns an object containing the data that was requested.

Responds with status code 400 if the namespace parameter, ns, is missing or invalid, or if the specified scope does not contain any data.

Request Parameters:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/food_app/favorites/dessert' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

{
  "data": "pistachio ice cream"
}

Delete custom data CustomDataController#delete_data

DELETE /api/v1/users/:user_id/custom_data(/*scope)

Delete custom user data.

Arbitrary JSON data can be stored for a User. This API call deletes that data for a given scope. Without a scope, all custom_data is deleted. See Store Custom Data for details and examples of storage and retrieval.

As an example, we’ll store some data, then delete a subset of it.

Example PUT with valid JSON data:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -X PUT \
  -F 'ns=com.my-organization.canvas-app' \
  -F 'data[fruit][apple]=so tasty' \
  -F 'data[fruit][kiwi]=a bit sour' \
  -F 'data[veggies][root][onion]=tear-jerking' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "fruit": {
      "apple": "so tasty",
      "kiwi": "a bit sour"
    },
    "veggies": {
      "root": {
        "onion": "tear-jerking"
      }
    }
  }
}

Example DELETE:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/fruit/kiwi' \
  -X DELETE \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "a bit sour"
}

Example GET following the above DELETE:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "fruit": {
      "apple": "so tasty"
    },
    "veggies": {
      "root": {
        "onion": "tear-jerking"
      }
    }
  }
}

Note that hashes left empty after a DELETE will get removed from the custom_data store. For example, following the previous commands, if we delete /custom_data/veggies/root/onion, then the entire /custom_data/veggies scope will be removed.

Example DELETE that empties a parent scope:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/veggies/root/onion' \
  -X DELETE \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": "tear-jerking"
}

Example GET following the above DELETE:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data' \
  -X GET \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "data": {
    "fruit": {
      "apple": "so tasty"
    }
  }
}

On success, this endpoint returns an object containing the data that was deleted.

Responds with status code 400 if the namespace parameter, ns, is missing or invalid, or if the specified scope does not contain any data.

Request Parameters:

curl 'https://<canvas>/api/v1/users/<user_id>/custom_data/fruit/kiwi' \
  -X DELETE \
  -F 'ns=com.my-organization.canvas-app' \
  -H 'Authorization: Bearer <token>'

!!!javascript
{
  "data": "a bit sour"
}

List course nicknames CourseNicknamesController#index

GET /api/v1/users/self/course_nicknames

Returns all course nicknames you have set.

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

Get course nickname CourseNicknamesController#show

GET /api/v1/users/self/course_nicknames/:course_id

Returns the nickname for a specific course.

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

Set course nickname CourseNicknamesController#update

PUT /api/v1/users/self/course_nicknames/:course_id

Set a nickname for the given course. This will replace the course’s name in output of API calls you make subsequently, as well as in selected places in the Canvas web user interface.

Request Parameters:

curl 'https://<canvas>/api/v1/users/self/course_nicknames/<course_id> \
  -X PUT \
  -F 'nickname=Physics' \
  -H 'Authorization: Bearer <token>'

Remove course nickname CourseNicknamesController#delete

DELETE /api/v1/users/self/course_nicknames/:course_id

Remove the nickname for the given course. Subsequent course API calls will return the actual name for the course.

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

Clear course nicknames CourseNicknamesController#clear

DELETE /api/v1/users/self/course_nicknames

Remove all stored course nicknames.

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