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
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.
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.
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.
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.
error: the server responded with status 404
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. |
{ "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=..." } } }