Documentation > Resources > Collection Items

Collection Items API

A collection item belongs to a collection, a user and currently references an artwork.

Retrieving Collection Items

If you're just trying to retrieve artworks that belong to a collection, use the artworks API.

You can retrieve collection items by following the "collection_items" link from a collection.

curl -v "https://api.artsy.net/api/collection_items?collection_id=...&user_id=..." -H "X-Access-Token:..."

This endpoint accepts the following parameters.

Name Value
collection_id Collection ID, required.
user_id Collection owner (user) ID, required.

The response is a paginated result with embedded collection items.

Retrieving a Collection Item

Users can retrieve a specific collection item by ID by rendering the "collection_item" link template from root.

curl -v "https://api.artsy.net/api/collection_items/{id}?collection_id=...&user_id=..." -H "X-Access-Token:..."

Creating and Updating Collection Items

You can create collection items with POST to "collection_items" and update a collection item, typically to change its position within a collection, with PUT to "collection_item".

The following Ruby example creates a collection and adds an artwork to it.

require 'hyperclient'

# access token should be obtained via OAuth
api = Hyperclient.new('https://api.artsy.net/api') do |api|
  api.headers['Accept'] = 'application/vnd.artsy-v2+json'
  api.headers['X-Access-Token'] = '...'
end

# retrieve current user
current_user = api.current_user

# fetch the user's default collection
collection = api.collections(user_id: current_user.id, default: true, private: true).first

# add an artwork to the collection
artwork = api.artworks.first
collection.collection_items._post(artwork_id: artwork.id)

Collection Item JSON Format

error: missing models

Links

Key Target
self The collection resource.
user User that owns the collection.
collection Collection that this item belongs to.
artwork Artwork referenced by this item.

Example

{
  "id" : "...",
  "created_at" : "2014-11-25T19:30:15+00:00",
  "updated_at" : "2014-11-25T19:30:15+00:00",
  "position" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.artsy.net/api/collection_items/...?collection_id=...&user_id=..."
    },
    "user" : {
      "href" : "https://api.artsy.net/api/users/..."
    },
    "collection" : {
      "href" : "https://api.artsy.net/api/collections/..."
    },
    "artwork" : {
      "href" : "https://api.artsy.net/api/artworks/..."
    }
  }
}