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

Sales API

Sales and Auctions are available at the sales endpoint.

Retrieving Sales

Users can retrieve sales by following the sales link from root.

curl -v "https://api.artsy.net/api/sales" -H "X-Access-Token: ACCESS_TOKEN"

This endpoint accepts the following parameters.

Name Value
live Boolean- filter live auctions only
is_auction Boolean- filter auctions only
published Boolean- limit to published sales

Only authorized users/applications may access unpublished sales=

The response is a paginated result with embedded sales.

{
  "total_count" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.artsy.net/api/sales?live=..."
    },
    "next" : {
      "href" : "https://api.artsy.net/api/sales?cursor=...&live=..."
    }
  },
  "_embedded" : {
    "sales" : [
      {
        "id":"...",
        ...
      }
    ]
  }
}

Retrieving a Sale

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

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

Sale JSON Format

error: the server responded with status 404

Example

{
  "id": "58126d67cd530e21c40002ec",
  "slug": "heritage-auctions-modern-and-contemporary-art-november-2016",
  "auction_state": "closed",
  "name": "Heritage Auctions: Modern & Contemporary Art (November 2016)",
  "is_preliminary": false,
  "is_auction": true,
  "is_live_integration": true,
  "start_at": "2016-10-28T20:00:00.000Z",
  "end_at": "2016-11-11T20:53:00.000Z",
  "time_zone": "Etc/UTC",
  "live_start_at": "2016-11-11T16:00:00.000Z",
  "registration_ends_at": "2016-11-10T16:00:00.000Z",
  "published": true,
  "has_buyers_premium": true,
  "bidding_engine_enabled": false,
  "sync_to_causality": true,
  "collect_payments": false,
  "created_at": "2016-10-27T21:11:03+00:00",
  "updated_at": "2024-10-07T15:48:44+00:00",
  "image_versions": [
    "wide",
    "source",
    "square",
    "large_rectangle"
  ],
  "_links": {
    "image": {
      "href": "https://d32dm0rphc51dk.cloudfront.net/-mPKXKz2s5qihBuv68bx-w/{image_version}.jpg",
      "templated": true
    },
    "self": {
      "href": "https://api.artsy.net/api/sales/58126d67cd530e21c40002ec"
    },
    "bidders": {
      "href": "https://api.artsy.net/api/bidders?sale_id=58126d67cd530e21c40002ec{&with_positions}",
      "templated": true
    },
    "artists": {
      "href": "https://api.artsy.net/api/artists?sale_id=58126d67cd530e21c40002ec{&sort,size}",
      "templated": true
    },
    "sale_artworks": {
      "href": "https://api.artsy.net/api/sale_artworks?sale_id=58126d67cd530e21c40002ec{&published}",
      "templated": true
    },
    "permalink": {
      "href": "https://www.artsy.net/auction/heritage-auctions-modern-and-contemporary-art-november-2016"
    }
  }
}