Public API Documentation > Resources > Collection Items
A collection item belongs to a collection, a user and currently references an artwork.
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.
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"
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)
error: the server responded with status 404
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. |
{ "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/..." } } }