Documentation > Resources > Collections

Collections API

A collection belongs to a user and contains artworks. A collection may be public or private: public collections are available for everyone to see and private collections are not. Every user has a default collection, often referred to as "Favorites" and called "Saved Artwork" by default.

Retrieving Collections

You can retrieve a user's public collections by following the "public_collections" link from a user. Users can retrieve their own public and private collections by following the collections link from user details.

curl -v "https://api.artsy.net/api/collections?user_id=...&private=true" -H "X-Access-Token:..."

This endpoint accepts the following parameters.

Name Value
user_id Collection owner (user) ID, required.
private Also retrieve private collections.

The response is a paginated result with embedded collections.

Retrieving a Collection

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

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

Users are only authorized to retrieve their own private collections.

Creating and Updating Collections

You can create a collection with POST to "collections" and update a collection with PUT on "collection". All fields from the collection JSON format below are supported, except "id". A "user_id" is required.

See this topic for documentation on how to add artworks to a collection.

Collection Item JSON Format

Key Description
id Unique id.
created_at Timestamp of when the record was created.
updated_at Timestamp of when the record was last updated.
name The name of the collection.
description The description of the collection.
default Default collection.
private Private or public collection.

Links

Key Target
self The collection resource.
user User that owns the collection.
artworks Artworks in this collection, sorted by position.
collection_items Collection Items in this collection.

Example

{
  "id" : "...",
  "created_at" : "2014-08-31T15:05:29+00:00",
  "updated_at" : "2014-08-31T15:05:29+00:00",
  "name" : "Saved Artwork",
  "description" : "Default collection, favorites.",
  "default" : true,
  "private" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.artsy.net/api/collections/..."},
    "user" : {
      "href" : "https://api.artsy.net/api/users/4dc805b18101da0001000489"
    },
    "artworks" : {
      "href" : "https://api.artsy.net/api/artworks?collection_id=...&user_id=..."
    },
    "collection_items" : {
      "href" : "https://api.artsy.net/api/collection_items?collection_id=...&user_id=..."
    }
  }
}