{"openapi":"3.0.3","info":{"title":"BidSpotter API (ReefAPI)","version":"1.0.2","description":"BidSpotter API - industrial & commercial auction catalogues, lots and live bids (bidspotter.com, bidspotter.co.uk) Call POST /bidspotter/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/bidspotter-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"BidSpotter API documentation","url":"https://reefapi.com/docs/bidspotter"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"bidspotter","description":"BidSpotter API - industrial & commercial auction catalogues, lots and live bids (bidspotter.com, bidspotter.co.uk)"}],"paths":{"/bidspotter/v1/auctions":{"post":{"operationId":"bidspotter_auctions","summary":"Auction catalogues on BidSpotter, one clean row per auction: title, auctioneer, date and time (UTC and as shown), type (timed / live webcast / tender), status (upcoming, ending now, closed …), locatio","description":"Auction catalogues on BidSpotter, one clean row per auction: title, auctioneer, date and time (UTC and as shown), type (timed / live webcast / tender), status (upcoming, ending now, closed …), location and address, lot categories with counts, image and catalogue link. Filter by auction type, country, state, auctioneer, category or association; current or past auctions; 60 per page with the site's own total.","tags":["bidspotter"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"string","enum":["us","uk"],"default":"us","description":"Which BidSpotter marketplace. bidspotter.com and bidspotter.co.uk list different auctions."},"status":{"type":"string","enum":["current","past"],"default":"current","description":"Current (incl. today's just-closed) or past auctions."},"auction_type":{"type":"string","enum":["timed","live","tender","catalogue"],"description":"Only timed online auctions, live webcasts, tenders or catalogue-only sales."},"country":{"type":"string","example":"United States","description":"Country of the auction, by name as the site lists it (United States, Canada, United Kingdom …; include_facets lists them)."},"state":{"type":"string","example":"Texas","description":"State / county, by name (include_facets lists them)."},"auctioneer":{"type":"string","example":"Myron Bowling Auctioneers","description":"Auctioneer by its exact name on the site (include_facets lists them)."},"category":{"type":"string","example":"FRK","description":"Lot category code (FRK = Forklifts, CAR = Cars, MCT = Machine Tools & Tools …; auctions[].categories[].code or include_facets)."},"master_category":{"type":"string","example":"IAC","description":"Top category code (IAC = Industrial & commercial, COV = Automotive & vehicles, MET = Metalworking, CAT = Food & beverage equipment …)."},"association":{"type":"string","example":"NAA","description":"Auctioneer association code (NAA, IAA, MDNA, AED, RICS)."},"sort":{"type":"string","enum":["date","auctioneer"],"description":"Order: date (default) or auctioneer."},"page":{"type":"integer","minimum":1,"maximum":500,"default":1,"description":"Page, from 1."},"exclude_closed":{"type":"boolean","default":false,"description":"Drop rows whose status is closed (today's finished sales stay on the current list). Paging and totals stay the site's own."},"include_facets":{"type":"boolean","default":false,"description":"Also return the site's filter values with counts (auctioneers, countries, states, categories …) — use them as filter values."}}},"example":{"page":1}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/bidspotter/v1/lots":{"post":{"operationId":"bidspotter_lots","summary":"The lots of one BidSpotter auction catalogue with the auction itself: every lot's number, title, description, image, opening price, current bid, bid count, next minimum bid, reserve met, closing time ","description":"The lots of one BidSpotter auction catalogue with the auction itself: every lot's number, title, description, image, opening price, current bid, bid count, next minimum bid, reserve met, closing time and location, plus the auction's dates, currency, buyer's premium, sales tax, venue address and auctioneer contact. Filter by keyword, category or brand; sort by lot number, closing time or bid.","tags":["bidspotter"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://www.bidspotter.com/en-us/auction-catalogues/witham/catalogue-id-witham10196","description":"A bidspotter.com or bidspotter.co.uk catalogue URL (any page of it), as in auctions[].url."},"auction_ref":{"type":"string","example":"witham10196","description":"The catalogue id (the part after catalogue-id- in its URL), as in auctions[].auction_ref. Use with site; the auctioneer is looked up."},"site":{"type":"string","enum":["us","uk"],"default":"us","description":"Which BidSpotter marketplace. bidspotter.com and bidspotter.co.uk list different auctions."},"page":{"type":"integer","minimum":1,"maximum":500,"default":1,"description":"Page, from 1."},"page_size":{"type":"string","enum":["60","120"],"default":"60","description":"Lots per page, as the site offers (60 or 120)."},"sort":{"type":"string","enum":["lot_number","newest","end_date","low_bid","high_bid"],"description":"Order of lots (webcasts support lot_number and newest only)."},"query":{"type":"string","example":"land rover","description":"Only lots matching these words inside this catalogue."},"category":{"type":"string","example":"CAR","description":"Only this lot category code (facets: categories)."},"brand":{"type":"string","example":"Land Rover","description":"Only this brand, as the site lists it (facets: brands)."},"include_bids":{"type":"boolean","default":true,"description":"Read the live bid state (current bid, bid count, next minimum bid, reserve met, closing time) from the site's bid service: one extra small request. false = only what the page itself carries (no bid counts)."},"include_facets":{"type":"boolean","default":false,"description":"Also return the site's filter values with counts (auctioneers, countries, states, categories …) — use them as filter values."}}},"example":{"url":"https://www.bidspotter.com/en-us/auction-catalogues/witham/catalogue-id-witham10196"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/bidspotter/v1/lot":{"post":{"operationId":"bidspotter_lot","summary":"One BidSpotter lot in full: title, lot number, the whole description, every image, current bid, bid count, opening price, next minimum bid, reserve met, buy-it-now, start and closing time, hammer pric","description":"One BidSpotter lot in full: title, lot number, the whole description, every image, current bid, bid count, opening price, next minimum bid, reserve met, buy-it-now, start and closing time, hammer price when sold and published, lot location, buyer's premium, sales tax, payment methods, removal / pickup notes, watchers, previous and next lot, the auction and the auctioneer's contact.","tags":["bidspotter"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://www.bidspotter.com/en-us/auction-catalogues/witham/catalogue-id-witham10196/lot-3930bb91-e312-4b7e-a996-b4ef00bb0b4e","description":"A bidspotter.com / bidspotter.co.uk lot URL (lots[].url)."},"auction_ref":{"type":"string","example":"witham10196","description":"The catalogue id (the part after catalogue-id- in its URL), as in auctions[].auction_ref. Use with site; the auctioneer is looked up."},"lot_id":{"type":"string","example":"3930bb91-e312-4b7e-a996-b4ef00bb0b4e","description":"The lot's UUID (lots[].lot_id); with auction_ref instead of url."},"site":{"type":"string","enum":["us","uk"],"default":"us","description":"Which BidSpotter marketplace. bidspotter.com and bidspotter.co.uk list different auctions."},"include_bids":{"type":"boolean","default":true,"description":"Read the live bid state (current bid, bid count, next minimum bid, reserve met, closing time) from the site's bid service: one extra small request. false = only what the page itself carries (no bid counts)."}}},"example":{"url":"https://www.bidspotter.com/en-us/auction-catalogues/witham/catalogue-id-witham10196/lot-3930bb91-e312-4b7e-a996-b4ef00bb0b4e"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/bidspotter/v1/search":{"post":{"operationId":"bidspotter_search","summary":"Search lots across every BidSpotter auction by keyword (forklift, cnc lathe, john deere …), narrowed by country, state, auction type, auctioneer, category or brand","description":"Search lots across every BidSpotter auction by keyword (forklift, cnc lathe, john deere …), narrowed by country, state, auction type, auctioneer, category or brand. Each row is a lot with its auction and auctioneer, prices, current bid, bid count and closing time, with the site's own total. Matching is the site's (fuzzy: forklift also finds fork lift / lift truck).","tags":["bidspotter"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"forklift","description":"Words to search lot titles and descriptions for."},"site":{"type":"string","enum":["us","uk"],"default":"us","description":"Which BidSpotter marketplace. bidspotter.com and bidspotter.co.uk list different auctions."},"country":{"type":"string","example":"United States","description":"Lot country, by name (facets: countries)."},"state":{"type":"string","example":"Ohio","description":"Lot state / county, by name (facets: states)."},"auction_type":{"type":"string","enum":["timed","live"],"description":"Only timed or only webcast lots."},"auctioneer":{"type":"string","description":"Auctioneer by its exact name (facets: auctioneers)."},"category":{"type":"string","example":"FRK","description":"Lot category code (facets: categories)."},"master_category":{"type":"string","example":"IAC","description":"Top category code (facets: master_categories)."},"brand":{"type":"string","example":"Toyota","description":"Brand, as the site lists it (facets: brands)."},"sort":{"type":"string","enum":["relevance","auction_date","auction_house","newest"],"description":"Order: relevance (default), auction_date, auction_house, newest."},"page":{"type":"integer","minimum":1,"maximum":500,"default":1,"description":"Page, from 1."},"include_bids":{"type":"boolean","default":true,"description":"Read the live bid state (current bid, bid count, next minimum bid, reserve met, closing time) from the site's bid service: one extra small request. false = only what the page itself carries (no bid counts)."},"include_facets":{"type":"boolean","default":false,"description":"Also return the site's filter values with counts (auctioneers, countries, states, categories …) — use them as filter values."}},"required":["query"]},"example":{"query":"forklift","include_bids":false}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/bidspotter/v1/bids":{"post":{"operationId":"bidspotter_bids","summary":"Live bid state for up to 120 BidSpotter lots in one call (timed and webcast): current bid, bid count, opening price, next minimum bid, reserve met, closing time and closed","description":"Live bid state for up to 120 BidSpotter lots in one call (timed and webcast): current bid, bid count, opening price, next minimum bid, reserve met, closing time and closed. For watching lots you already know without re-reading the catalogue.","tags":["bidspotter"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lot_ids":{"type":"array","items":{"type":"string"},"example":["3930bb91-e312-4b7e-a996-b4ef00bb0b4e","5530e1e2-2ea8-40fb-9481-b4ef00bb2fee"],"description":"Lot UUIDs (lots[].lot_id), up to 120."},"site":{"type":"string","enum":["us","uk"],"default":"us","description":"Which BidSpotter marketplace. bidspotter.com and bidspotter.co.uk list different auctions."}},"required":["lot_ids"]},"example":{"lot_ids":["3930bb91-e312-4b7e-a996-b4ef00bb0b4e","5530e1e2-2ea8-40fb-9481-b4ef00bb2fee"]}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}