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",
    "large_rectangle",
    "square",
    "source"
  ],
  "_links": {
    "thumbnail": {
      "href": "https://d32dm0rphc51dk.cloudfront.net/-mPKXKz2s5qihBuv68bx-w/wide.jpg"
    },
    "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"
    }
  }
}