Please note, we are in the process of retiring the public api. The public api, as well as its documentation and playground, will remain available until July 28th, 2025. This change will not affect integration partners using our partner api.


If you're an Artsy partner gallery, reach out to your Artsy Liaison or contact our Support team for assistance.

Public API 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=USER_ID&private=true" -H "X-Access-Token: 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=USER_ID" -H "X-Access-Token: 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

error: the server responded with status 404

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