Content Shares API

API for creating, accessing and updating Content Sharing. Content shares are used to share content directly between users.

A ContentShare object looks like:

// Content shared between users
{
  // The id of the content share for the current user
  "id": 1,
  // The name of the shared content
  "name": "War of 1812 homework",
  // The type of content that was shared. Can be assignment, discussion_topic,
  // page, quiz, module, or module_item.
  "content_type": "assignment",
  // The datetime the content was shared with this user.
  "created_at": "2017-05-09T10:12:00Z",
  // The datetime the content was updated.
  "updated_at": "2017-05-09T10:12:00Z",
  // The id of the user who sent or received the content share.
  "user_id": 1578941,
  // The user who shared the content. This field is provided only to receivers; it
  // is not populated in the sender's list of sent content shares.
  "sender": {"id":1,"display_name":"Matilda Vargas","avatar_image_url":"http:\/\/localhost:3000\/image_url","html_url":"http:\/\/localhost:3000\/users\/1"},
  // An Array of users the content is shared with.  This field is provided only to
  // senders; an empty array will be returned for the receiving users.
  "receivers": [{"id":1,"display_name":"Jon Snow","avatar_image_url":"http:\/\/localhost:3000\/image_url2","html_url":"http:\/\/localhost:3000\/users\/2"}],
  // The course the content was originally shared from.
  "source_course": {"id":787,"name":"History 105"},
  // Whether the recipient has viewed the content share.
  "read_state": "read",
  // The content export record associated with this content share
  "content_export": {"id":42}
}

Create a content share ContentSharesController#create

POST /api/v1/users/:user_id/content_shares

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

Share content directly between two or more users

Request Parameters:

Parameter Type Description
receiver_ids Required Array

IDs of users to share the content with.
content_type Required string

Type of content you are sharing.

Allowed values: assignment, discussion_topic, page, quiz, module, module_item

content_id Required integer

The id of the content that you are sharing

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares \
      -d 'content_type=assignment' \
      -d 'content_id=1' \
      -H 'Authorization: Bearer <token>' \
      -X POST
Returns a ContentShare object

List content shares ContentSharesController#index

GET /api/v1/users/:user_id/content_shares/sent

Scope: url:GET|/api/v1/users/:user_id/content_shares/sent

GET /api/v1/users/:user_id/content_shares/received

Scope: url:GET|/api/v1/users/:user_id/content_shares/received

Return a paginated list of content shares a user has sent or received. Use self as the user_id to retrieve your own content shares. Only linked observers and administrators may view other users’ content shares.

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares/received'
Returns a list of ContentShare objects

Get unread shares count ContentSharesController#unread_count

GET /api/v1/users/:user_id/content_shares/unread_count

Scope: url:GET|/api/v1/users/:user_id/content_shares/unread_count

Return the number of content shares a user has received that have not yet been read. Use self as the user_id to retrieve your own content shares. Only linked observers and administrators may view other users’ content shares.

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares/unread_count'

Get content share ContentSharesController#show

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

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

Return information about a single content share. You may use self as the user_id to retrieve your own content share.

Example Request:

curl 'https://<canvas>/api/v1/users/self/content_shares/123'
Returns a ContentShare object

Remove content share ContentSharesController#destroy

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

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

Remove a content share from your list. Use self as the user_id. Note that this endpoint does not delete other users’ copies of the content share.

Example Request:

curl -X DELETE 'https://<canvas>/api/v1/users/self/content_shares/123'

Add users to content share ContentSharesController#add_users

POST /api/v1/users/:user_id/content_shares/:id/add_users

Scope: url:POST|/api/v1/users/:user_id/content_shares/:id/add_users

Send a previously created content share to additional users

Request Parameters:

Parameter Type Description
receiver_ids Array

IDs of users to share the content with.

Example Request:

curl -X POST 'https://<canvas>/api/v1/users/self/content_shares/123/add_users?receiver_ids[]=789'
Returns a ContentShare object

Update a content share ContentSharesController#update

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

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

Mark a content share read or unread

Request Parameters:

Parameter Type Description
read_state string

Read state for the content share

Allowed values: read, unread

Example Request:

curl -X PUT 'https://<canvas>/api/v1/users/self/content_shares/123?read_state=read'
Returns a ContentShare object