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 Title.
category Category.
medium Medium.
date Date, can be a range or a year.
published Whether artwork is available for public consumption.
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 Provenance.
literature Mentions of the work in publications.
exhibition_history Exhibition history.
collecting_institution Collecting institution.
additional_information Additional artwork information.
image_rights Additional image rights.
blurb Short text blurb about the artwork.
cultural_maker Can be substituted for artist when no artist is available.
iconicity A score that tells us how important an artwork is within the artist body of work.
can_inquire True when the artwork 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 on social networks.
sale_message Purchasing information, which may include price.
sold True if the artwork 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.0378117418529,
  "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"
    }
  },
  "_embedded": {
    "editions": [

    ]
  }
}