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 > 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: 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: 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

error: the server responded with status 429

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": "2024-09-28T07:31:01+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.245520919676473,
  "can_inquire": false,
  "can_acquire": false,
  "can_share": true,
  "sale_message": null,
  "sold": false,
  "visibility_level": "listed",
  "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": "https://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"
    },
    "sale_artworks": {
      "href": "https://api.artsy.net/api/sale_artworks?artwork_id=516dfb9ab31e2b2270000c45"
    }
  },
  "_embedded": {
    "editions": [

    ]
  }
}