Skip to content

API for developers

Read the AuctionFinder data as JSON. The API is free, needs no key and reads only. Base URL: https://auctionfinder.fyi/api/v1.

The OpenAPI 3.1 description is at /api/v1/openapi.json. Any website may call the API from a browser.

Endpoints

Each endpoint in this table takes GET. Any other method gives 405. A parameter that is not listed gives 400.

Endpoints of the AuctionFinder API, with their parameters
EndpointReturnsParameters
GET /api/v1/listingsSearch and list listings
q (query, optional, string)
Search text, with at least one letter or digit. Matches name, categories, attributes, description and place. Typos fall back to close matches.
country (query, optional, string)
ISO 3166-1 alpha-2 country code, any case. A country the directory does not cover, as listed in /places, gives 400.
region (query, optional, string)
Region slug, from /places.
city (query, optional, string)
City slug, from /places.
category (query, optional, string)
Category slug, from /categories. A parent slug also matches its children.
sort (query, optional, one of: relevance, name, recent)
relevance needs q and is the default with it. name is the default without q. recent is newest first.
limit (query, optional, integer, 1 to 50, default 20)
Items per page.
cursor (query, optional, string)
page.nextCursor from the previous response. Opaque. Send the same filters and limit.
GET /api/v1/listings/{slug}Read one listing
slug (path, required, string)
The listing slug.
GET /api/v1/placesList countries, regions and cities with countsNone
GET /api/v1/categoriesList the category tree with countsNone
GET /api/v1/sourcesList the data sources with license and refreshNone
GET /api/v1/statsCounts and the last updateNone

Examples

Find auction houses and platforms

curl "https://auctionfinder.fyi/api/v1/listings?category=auctions&country=US&limit=5"

Read the next page

curl "https://auctionfinder.fyi/api/v1/listings?limit=5&cursor=<page.nextCursor from the last response>"

Read one auction house or platform

slug=$(curl -s "https://auctionfinder.fyi/api/v1/listings?limit=1" | jq -r '.data[0].slug')
curl "https://auctionfinder.fyi/api/v1/listings/$slug"

List the places and categories you can filter by

curl "https://auctionfinder.fyi/api/v1/places"
curl "https://auctionfinder.fyi/api/v1/categories"

MCP server

An AI agent can use the same data through MCP at https://auctionfinder.fyi/mcp. It takes POST only: a GET in a browser gives 405. The server uses Streamable HTTP, keeps no session and needs no key. It reads only. It has the same rate limit, the same public fields and the same credit line as the API. The server card describes it.

search_listings
: Search published auction houses and platforms by text, place and category.
get_listing
: Get one published auction house or platform by its slug.
list_places
: List countries, regions and cities that have auction houses and platforms.
list_categories
: List categories with their auction house or platform counts.
get_stats
: Get the number of published auction houses and platforms, places and categories, and when the data last changed.
list_sources
: List where the auction house or platform data comes from, with the license and refresh of each source.

Add it to Claude Code

claude mcp add --transport http auctionfinder https://auctionfinder.fyi/mcp

Add it to a client that reads an mcpServers file, such as Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "auctionfinder": {
      "url": "https://auctionfinder.fyi/mcp"
    }
  }
}

List the tools with curl

curl -X POST "https://auctionfinder.fyi/mcp" -H "content-type: application/json" -H "accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Responses

A successful response has data and meta. A list response also has page, with these fields:

limit
: items on each page.
total
: items that match.
nextCursor
: send it back as cursor, with the same filters and limit. It is null on the last page.
capped
: true when more items match than the cursor can reach.
fuzzy
: true when the items are close matches for q.

An error has error (a sentence), code and sometimes details. Branch on code: invalid_parameter, invalid_cursor, not_found, method_not_allowed, rate_limited, internal_error.

Rate limits and caching

Each client may send 300 requests in 60 seconds. Every GET response has RateLimit-Limit and RateLimit-Policy. Over the limit you get 429 with Retry-After: wait that many seconds. The limit is counted at each Cloudflare location.

A successful response sends Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600 and an ETag. Send the ETag back as If-None-Match to get 304 with no body.

Credit and licenses

Show this credit line next to the data you display:

Data from AuctionFinder (https://auctionfinder.fyi). Each record keeps the license of its source, listed in meta.sources. A listing is a record, not an endorsement.

Every response lists its sources in meta.sources. Keep a source's license when you reuse its records.

  • OpenStreetMap: Frank G Bowen Ltd: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • OpenStreetMap: High Road Auctions: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • OpenStreetMap: Greasby's Auctioneers: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • OpenStreetMap: Essex Auction House: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • OpenStreetMap: Sotheby's Auction House: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • OpenStreetMap: Phillips: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • OpenStreetMap: The Auction Room: license Open Database License (ODbL) 1.0, (c) OpenStreetMap contributors. See data/reports/osm.md for share-alike notes., refreshed manual
  • GSA Auctions: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • New York State Surplus Property: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • North Carolina State Surplus Property Agency: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • Pennsylvania DGS Surplus: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • Texas State Surplus Property Program: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • California State Surplus Property Program: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • Florida DMS Surplus Vehicle Auctions: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • GCSurplus: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • VEBEG: license US federal pages are public domain works (17 U.S.C. 105); the GSA Auctions dataset on catalog.data.gov is CC0-1.0. State, provincial and foreign program pages are cited facts with links, not copied content., refreshed quarterly
  • Christie's: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Heritage Auctions: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Bonhams: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • LiveAuctioneers: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Invaluable: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • The Saleroom: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • HiBid: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • BidSpotter: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Catawiki: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Drouot: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Troostwijk Auctions: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • GovDeals: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • Pickles Auctions: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly
  • John Pye Auctions: license Each house's own published terms or premium page. The directory records short facts and links to the page; no marketing text is copied., refreshed monthly

Published by . How we check each auction house or platform.

The auction newsletter

A short email now and again: a new house or program worth knowing, a premium change worth checking and one fraud warning. No noise.

We only use your email to send this newsletter. Privacy policy.