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://stagingapi.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://stagingapi.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://stagingapi.artsy.net/api/collections/..."},
    "user" : {
      "href" : "https://stagingapi.artsy.net/api/users/4dc805b18101da0001000489"
    },
    "artworks" : {
      "href" : "https://stagingapi.artsy.net/api/artworks?collection_id=...&user_id=..."
    },
    "collection_items" : {
      "href" : "https://stagingapi.artsy.net/api/collection_items?collection_id=...&user_id=..."
    }
  }
}