Public API 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=USER_ID" -H "X-Access-Token: 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=USER_ID" -H "X-Access-Token: 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: the server responded with status 404

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/..."
    }
  }
}