Collections API

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

Collections are buckets of content that can be used to organize links to helpful resources. For instance, a user could create a collection storing a set of links to various web sites containing potential discussion questions, or members of a group could all contribute to a collection focused on potential assessment questions.

A user/group can have multiple collections, and each can be marked as private (viewable only to the user/group) or public (viewable by the world).

Group collections can only be created, updated, or deleted by group moderators.

Collections contain Collection Items, which are links to content. There are different types of items for links to different types of data.

Collection items can be cloned from other collection items. This way the original source of the item can be tracked, and a count of "re-posts" can be kept on each item to track popularity. Note that depending on where the original item came from, a user may be able to view the cloned item but not the original item.

A collection item also has a Discussion Topic associated with it, which can be used for comments on the item. See the Discussion Topic API for details on querying and adding to a discussion. The scope for the discussion topic will be the collection item, and the id of the topic is "self". For example, the DiscussionTopicsApiController#view endpoint looks like this:

/api/v1/collection_items/<id>/discussion_topics/self/view

A Collection object looks like:

{
  // The ID of the collection.
  id: 5,

  // The display name of the collection, set by the collection creator.
  name: "My Collection",

  // The visibility of the collection. If "public", the collection is
  // visible to everybody, and can be followed.  If "private", the
  // collection is visible only to the creating user.
  // The default is "private".
  visibility: "public",

  // Boolean indicating whether this user is following this collection.
  followed_by_user: false,

  // The number of people following this collection.
  followers_count: 10,

  // The number of items in this collection.
  items_count: 7
}

A Collection Item object looks like:

{
  // The ID of the collection item.
  id: 7,

  // The ID of the collection that this item belongs to.
  collection_id: 2,

  // The type of the item.
  // Currently defined types are: "url", "image", "audio", and "video".
  //
  // Canvas may define new item types at any time. "url" is the most
  // generic type, and just means any sort of web link. If an api consumer
  // sees an item_type that it doesn't yet know how to handle, treating it
  // as a "url" is a safe bet.
  //
  // "image", "audio" and "video" are URLs either directly to a file of that mime type, or
  // to a web page that was determined to contain that type as its main content.
  item_type: "url",

  // The link to the item. For item type of "url", this is the entire
  // contents of the collection item. For other item types, this may be a
  // web preview or other representation of the item data.
  link_url: "https://example.com/some/path",

  // The number of posts of this item, including the original. This count
  // is shared between the original item and all clones.
  post_count: 2,

  // The number of users who have voted up this item. This count is
  // shared between the original item and all clones.
  upvote_count: 3,

  // Boolean indicating whether this user has upvoted this item (or any of its clones)
  upvoted_by_user: false,

  // If this item was cloned from another item, this will be the ID of
  // the first, original item that all clones are derived from.
  // In other words, if item 7 was cloned from item 5, and
  // 5 was cloned from item 3, and 3 is the original, then the
  // root_item_id of items 7, 5 and 3 will all be 3.
  root_item_id: 3,

  // An image representation of the collection item. This will be in a
  // common web format such as png or jpeg. The resolution and geometry may depend on
  // the item, but Canvas will attempt to make it 640 pixels wide
  // when possible.
  image_url: "https://<canvas>/files/item_image.png",

  // If true, the image for this item is still being processed and
  // image_url will be null. Check back later.
  // If image_url is null but image_pending is false, the item has no image.
  image_pending: false,

  // The title of the item.
  title: "My Image",

  // The description of the item. This is plain text.
  description: "some block of plain text",

  // Any user-provided comments on the item. A user can add their own
  // comments when cloning an existing item. This is plain text.
  user_comment: "some block of plain text",

  // A snippet of HTML that can be used as an in-line preview of the
  // item. For example, a link to a youtube page may have an iframe inline
  // embed of the video.
  // If no preview is available, this field will be null.
  html_preview: "<iframe>...</iframe>",

  // The API URL for this item. Used to clone the collection item.
  url: "https://<canvas>/api/v1/collections/items/7"

  // The timestamp of when the item was posted by the user
  created_at: "2012-05-30T17:45:25Z",

  // Information on the user that created the collection item.
  user : {
    // The ID of the user.
    id: 37,

    // The display name of the user.
    display_name: "John Doe",

    // The URL of the user's avatar image, or a fallback image if the user has not given one.
    avatar_image_url: "http://...",

    // The URL to the HTML page in Canvas of this user's public profile.
    html_url: "http://<canvas>/users/37"
  },
}

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.

Example Request:

curl -H 'Authorization: Bearer <token>' \ 
     https://<canvas>/api/v1/users/self/collections
Returns a list of 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.

Example Request:

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.

Example Request:

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

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

Example Request:

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

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.

Example Request:

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

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.

Example Request:

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

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

Example Request:

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

Example Response:

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

Example Request:

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.

Example Request:

curl https://<canvas>/api/v1/collections/<collection_id>/items \ 
     -H 'Authorization: Bearer <token>'
Returns a list of Collection Items

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.

Example Request:

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

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.

Example Request:

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>'
Returns a Collection Item

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

Example Request:

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

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.

Example Request:

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

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.

Example Request:

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

Example Response:

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

Example Request:

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