Documentation > Resources > Artworks

Artworks API

An artwork is an artistic production created by an artist, multiple artists or an artist collective. An artwork may be part of a series and be reproduced in prints. Artworks are available from Artsy partners and may be included in shows.

Retrieving Artworks

Retrieve artworks by following the artworks link from root.

curl -v "https://api.artsy.net/api/artworks" -H "X-XAPP-Token:..."

This endpoint accepts the following parameters.

Name Value
artist_id Retrieve artworks by a given artist.
partner_id Retrieve artworks that belong to a given partner.
show_id Retrieve artworks that belong to a given show.
collection_id Retrieve artworks that belong to a given collection, sorted by position.
user_id The user that owns the collection, required when collection_id is specified.

The response is a paginated result with embedded artworks.

Retrieving an Artwork

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

curl -v "https://api.artsy.net/api/artworks/{id}" -H "X-XAPP-Token:..."

Retrieving Similar Artworks

Artsy continuously computes a K-nearest-neighbor graph for artworks using data from the Art Genome Project. Retrieve artworks similar to another artwork by following the "similar_artworks" link in an artwork resource, which calls this endpoint with the similar\_to\_artwork_id parameter. The response is a non-paginated set of similar artworks.

Artwork JSON Format

Key Description
id Unique id.
slug Unique slug.
created_at Timestamp of when the record was created.
updated_at Timestamp of when the record was last updated.
title The title of a piece.
category The medium type, such as "painting", "photography", "video", etc. Generally used for broad filters.
medium Medium, materials and techniques used to make a piece.
date Date, can be a range, a year or a period.
published Whether the work is visible on artsy.net.
website Website, typically for net art.
signature Artist signature, when present on the artwork.
series Information about the series this work is part of.
provenance The history of the various ways the work has changed hands.
literature Mentions of the work in publications.
exhibition_history Exhibition history of the work.
collecting_institution (Deprecated) The institution which holds the work in their permanent collection.
additional_information Additional work information from the partner.
image_rights Image rights for the work.
blurb Short text blurb about the work.
cultural_maker A cultural/geographic attribution, used instead of an artist when the maker is anonymous.
iconicity A generated score that tells us how important a work is within the artist's body of works.
can_inquire True when the work can be inquired on with an Artsy representative.
can_acquire True when the artwork can be acquired from Artsy via e-commerce.
can_share Allow sharing of the work and images on social networks.
sale_message The work's commercial availability, which may include price.
sold True if the work has been sold.
image_versions Available image versions.

Links

Key Target
self The artwork resource.
thumbnail Default image thumbnail.
image Curied image location.
permalink An external location on the artsy.net website.
partner Partner that owns the artwork.
artists Artwork's Artists.
genes Artwork's Genes.
similar_artworks Artwork similar to the artwork.

Embedded Collections

Key Target
editions A set of artwork editions available for this artwork.

Example

{
  "id": "516dfb9ab31e2b2270000c45",
  "slug": "william-michael-harnett-the-old-violin",
  "created_at": "2013-04-17T01:32:10+00:00",
  "updated_at": "2016-06-14T06:52:53+00:00",
  "title": "The Old Violin",
  "category": "Painting",
  "medium": "Oil on canvas",
  "date": "1886",
  "dimensions": {
    "in": {
      "text": "38 × 23 5/8 in",
      "height": 38.0,
      "width": 23.625,
      "depth": null,
      "diameter": null
    },
    "cm": {
      "text": "96.5 × 60 cm",
      "height": 96.5,
      "width": 60.0,
      "depth": null,
      "diameter": null
    }
  },
  "published": true,
  "website": "",
  "signature": "",
  "series": "",
  "provenance": "",
  "literature": "",
  "exhibition_history": "",
  "collecting_institution": "National Gallery of Art, Washington D.C.",
  "additional_information": "\n    overall: 96.5 x 60 cm (38 x 23 5/8 in.)  framed: 119.7 x 84.1 x 5.1 cm (47 1/8 x 33 1/8 x 2 in.)\n    ",
  "image_rights": "Courtesy National Gallery of Art, Washington",
  "blurb": "",
  "unique": false,
  "cultural_maker": null,
  "iconicity": 25.0633289532584,
  "can_inquire": false,
  "can_acquire": false,
  "can_share": true,
  "sale_message": null,
  "sold": false,
  "image_versions": [
    "large",
    "large_rectangle",
    "larger",
    "medium",
    "medium_rectangle",
    "normalized",
    "square",
    "tall"
  ],
  "_links": {
    "thumbnail": {
      "href": "https://d32dm0rphc51dk.cloudfront.net/dTGcd0Xx0aEp_MDFdHIUIw/medium.jpg"
    },
    "image": {
      "href": "https://d32dm0rphc51dk.cloudfront.net/dTGcd0Xx0aEp_MDFdHIUIw/{image_version}.jpg",
      "templated": true
    },
    "partner": {
      "href": "https://api.artsy.net/api/partners/4f99c7b793ab4b0001000179"
    },
    "self": {
      "href": "https://api.artsy.net/api/artworks/516dfb9ab31e2b2270000c45"
    },
    "permalink": {
      "href": "http://www.artsy.net/artwork/william-michael-harnett-the-old-violin"
    },
    "genes": {
      "href": "https://api.artsy.net/api/genes?artwork_id=516dfb9ab31e2b2270000c45"
    },
    "artists": {
      "href": "https://api.artsy.net/api/artists?artwork_id=516dfb9ab31e2b2270000c45"
    },
    "similar_artworks": {
      "href": "https://api.artsy.net/api/artworks?similar_to_artwork_id=516dfb9ab31e2b2270000c45"
    },
    "collection_users": {
      "href": "https://api.artsy.net/api/users?collected_artwork_id=516dfb9ab31e2b2270000c45"
    }
  },
  "_embedded": {
    "editions": [

    ]
  }
}