# Content Shares

{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}

## 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:**

```js
// 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](#method.content_shares.create) <a href="#method.content_shares.create" id="method.content_shares.create"></a>

[ContentSharesController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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`  | <p>Type of content you are sharing.</p><p>Allowed values: <code>assignment</code>, <code>discussion\_topic</code>, <code>page</code>, <code>quiz</code>, <code>module</code>, <code>module\_item</code></p> |
| `content_id`   | Required `integer` | The id of the content that you are sharing                                                                                                                                                                  |

**Example Request:**

```bash
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](#contentshare) object.

### [List content shares](#method.content_shares.index) <a href="#method.content_shares.index" id="method.content_shares.index"></a>

[ContentSharesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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:**

```bash
curl 'https://<canvas>/api/v1/users/self/content_shares/received'
```

Returns a list of [ContentShare](#contentshare) objects.

### [Get unread shares count](#method.content_shares.unread_count) <a href="#method.content_shares.unread_count" id="method.content_shares.unread_count"></a>

[ContentSharesController#unread\_count](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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:**

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

### [Get content share](#method.content_shares.show) <a href="#method.content_shares.show" id="method.content_shares.show"></a>

[ContentSharesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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:**

```bash
curl 'https://<canvas>/api/v1/users/self/content_shares/123'
```

Returns a [ContentShare](#contentshare) object.

### [Remove content share](#method.content_shares.destroy) <a href="#method.content_shares.destroy" id="method.content_shares.destroy"></a>

[ContentSharesController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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:**

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

### [Add users to content share](#method.content_shares.add_users) <a href="#method.content_shares.add_users" id="method.content_shares.add_users"></a>

[ContentSharesController#add\_users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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:**

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

Returns a [ContentShare](#contentshare) object.

### [Update a content share](#method.content_shares.update) <a href="#method.content_shares.update" id="method.content_shares.update"></a>

[ContentSharesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_shares_controller.rb)

**`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` | <p>Read state for the content share</p><p>Allowed values: <code>read</code>, <code>unread</code></p> |

**Example Request:**

```bash
curl -X PUT 'https://<canvas>/api/v1/users/self/content_shares/123?read_state=read'
```

Returns a [ContentShare](#contentshare) object.

***

This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developerdocs.instructure.com/services/canvas/resources/content_shares.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.