# HiBid — US & Canada auction aggregator (lots, bids, sales, houses)

> Search HiBid's whole catalogue of live and timed online auction lots across thousands of independent North-American auction houses, or its closed archive. Every row names the auction house it belongs to — name, town, state, country, phone, e-mail and its own website — plus the sale it sits in and the HiBid lot URL, so any lot can be traced back to the house that is selling it. Live bidding state comes with it: current bid, number of bids, next bid required, buy-now, reserve status and the lot's own closing instant in UTC. Every filter is optional, but pass at least one of `query`, `category_id`, `auction_id`, `lot_ids`, `state` or `zip` — with none of them you get the newest slice of the entire catalogue.
> ReefAPI engine `hibid` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/hibid/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/hibid/v1/search — 1 credit
Search HiBid's whole catalogue of live and timed online auction lots across thousands of independent North-American auction houses, or its closed archive. Every row names the auction house it belongs to — name, town, state, country, phone, e-mail and its own website — plus the sale it sits in and the HiBid lot URL, so any lot can be traced back to the house that is selling it. Live bidding state comes with it: current bid, number of bids, next bid required, buy-now, reserve status and the lot's own closing instant in UTC. Every filter is optional, but pass at least one of `query`, `category_id`, `auction_id`, `lot_ids`, `state` or `zip` — with none of them you get the newest slice of the entire catalogue.

**Parameters:**
- `query` (string, optional) — Free-text search over the lot title and description (e.g. 'rolex', 'john deere 4020', 'morgan silver dollar'). Optional: leave it out and narrow with category_id, auction_id or state instead.
- `status` (enum, optional, default "open") — Which lots to return. 'open' = still taking bids, 'closed' = bidding over, 'all' = both. 'hot', 'top' and 'featured' are HiBid's own selections. [one of: all, open, closing, closed, hot, featured, top]
- `archive` (boolean, optional, default false) — Search HiBid's closed archive instead of the current catalogue. The archive answers at most 1,000 lots per query (the live surface answers 10,000) and is measurably slower.
- `lot_type` (enum, optional, default "all") — Sale format. 'online' = timed online-only, 'webcast' = live webcast/simulcast, 'listing' = catalogue listing with no HiBid bidding. [one of: all, biddable, online, webcast, absentee, listing]
- `sort` (enum, optional, default "lot_number") — Row order. Keep the default when you page: HiBid returns a RANDOM SAMPLE when no order is given, so an unordered 'page 2' is not the second page of anything. [one of: lot_number, newest, ending_soonest, sale_order, bid_high_first, bid_low_first, most_bids, fewest_bids, most_viewed, most_watched, last_bid, hot_rank]
- `category_id` (integer, optional) — Restrict to one HiBid category id. Call the `categories` action for the tree (18 roots, 1,135 nodes measured). An id HiBid does not know is rejected here, because the site silently ignores it and answers with the whole catalogue.
- `auction_id` (integer, optional) — Restrict to one sale (auction event) by its HiBid id — this is also how you read every lot of one auction house, since HiBid publishes no house filter on lots. Get the ids from the `auctions` action.
- `lot_ids` (string, optional) — Up to 100 HiBid lot ids, comma-separated — returns exactly those lots in one call instead of one `detail` call each. Ids come from `search`; the auction house's own item number does not work here.
- `state` (string, optional) — US state / Canadian province, TWO-LETTER CODE ONLY (TX, OH, BC). HiBid answers zero rows for a spelled-out name, so a name is rejected here with the reason.
- `country` (enum, optional) — Country of the auction house. Pass it as HiBid's rows spell it. 'USA', 'US' and 'America' are accepted and mapped onto 'United States', because sending 'USA' straight through loses about 90% of the rows without any error (measured: 'United States' 21 lots, 'USA' 2, on a 24-lot query). [one of: United States, Canada]
- `zip` (string, optional) — US/Canadian postcode to search around. Pair it with `radius_miles`.
- `radius_miles` (integer, optional, default 50) — Miles around `zip`. Ignored unless `zip` is set.
- `shipping_offered` (boolean, optional, default false) — Only lots whose auction house offers shipping.
- `page` (integer, optional, default 1) — 1-based page. HiBid serves at most 10,000 lots per query (1,000 on the archive), so the last reachable page is that cap divided by max_results.
- `max_results` (integer, optional, default 25) — Rows per page, 1-100. HiBid's own ceiling is 100: asking for 200 returns 100.

**Returns:** {query, status, archive, sort, filters, total_available, total_is_capped, page, page_count, duplicate_ids_in_page, currencies, results[]} — each result carries lot_id, url, title, description, lot_number, quantity, estimate, currency, current_bid, bid_count, next_bid_amount, price_realized, price_realized_note, reserve_met, state, is_closed, is_sold, closes_at, closes_at_source, time_left_seconds, images, picture_count, shipping_offered, auction{...} and auction_house{...}.

**Example request body:**
```json
{
  "query": "rolex",
  "max_results": 10
}
```

### POST https://api.reefapi.com/hibid/v1/detail — 1 credit
One lot in full: every picture, the full category path, the lot's live bidding state, and the sale's complete terms — buyer's premium, bid increments, payment, shipping and pickup, preview and checkout dates, terms and conditions — together with the auction house's own contact details and website. Add `include_bids` for the public bid ladder in the same call. A lot whose bidding has closed is a normal answer, not an error; a lot the house has hidden or deleted comes back as NOT_FOUND and is not retried.

**Parameters:**
- `lot` (string, required) — The numeric HiBid lot id, or any hibid.com lot URL such as https://hibid.com/lot/320966322. The auction house's own item number is NOT accepted — HiBid answers 'hidden' for it.
- `include_bids` (boolean, optional, default true) — Also fetch the lot's public bid ladder (one extra upstream call, skipped automatically when the call budget is nearly spent and then counted in meta).

**Returns:** One lot object — the search row plus pictures[], category_path[], auction.terms{...}, auction.bid_increments[] and (with include_bids) bids[] {amount, bidder, bids_at_this_amount, placed_at_source}.

**Example request body:**
```json
{
  "lot": "320966322"
}
```

### POST https://api.reefapi.com/hibid/v1/bids — 1 credit
The public bid ladder of one lot: each amount, how many bids were placed at it, the timestamp HiBid prints and the bidder name HiBid itself masks. `bid_count` on the lot counts BIDS, this list counts AMOUNTS, so the two differ on purpose (measured: bid_count 16 against 3 ladder rows).

**Parameters:**
- `lot` (string, required) — The numeric HiBid lot id or a hibid.com lot URL.

**Returns:** {lot_id, url, title, lot_number, currency, bid_count, highest_bid, disclaimer, bids[]} — bids newest-amount first.

**Example request body:**
```json
{
  "lot": "320966322"
}
```

### POST https://api.reefapi.com/hibid/v1/auctions — 1 credit
Search the SALES rather than the lots: which auctions are running or coming up, how many lots each holds, when bidding opens and closes, where the sale is, what the buyer's premium is, and which auction house is running it. This is also the way to work house-by-house, because the lot search publishes no house filter: take `auction_id` from here into `search`.

**Parameters:**
- `query` (string, optional) — Free-text search over the lot title and description (e.g. 'rolex', 'john deere 4020', 'morgan silver dollar'). Optional: leave it out and narrow with category_id, auction_id or state instead.
- `status` (enum, optional, default "open") — Which lots to return. 'open' = still taking bids, 'closed' = bidding over, 'all' = both. 'hot', 'top' and 'featured' are HiBid's own selections. [one of: all, open, closing, closed, hot, featured, top]
- `lot_type` (enum, optional, default "all") — Sale format. 'online' = timed online-only, 'webcast' = live webcast/simulcast, 'listing' = catalogue listing with no HiBid bidding. [one of: all, biddable, online, webcast, absentee, listing]
- `auction_sort` (enum, optional, default "default") — Sale order. 'nearest' needs `zip`. [one of: nearest, default]
- `category_id` (integer, optional) — Restrict to one HiBid category id. Call the `categories` action for the tree (18 roots, 1,135 nodes measured). An id HiBid does not know is rejected here, because the site silently ignores it and answers with the whole catalogue.
- `state` (string, optional) — US state / Canadian province, TWO-LETTER CODE ONLY (TX, OH, BC). HiBid answers zero rows for a spelled-out name, so a name is rejected here with the reason.
- `country` (enum, optional) — Country of the auction house. Pass it as HiBid's rows spell it. 'USA', 'US' and 'America' are accepted and mapped onto 'United States', because sending 'USA' straight through loses about 90% of the rows without any error (measured: 'United States' 21 lots, 'USA' 2, on a 24-lot query). [one of: United States, Canada]
- `zip` (string, optional) — US/Canadian postcode to search around. Pair it with `radius_miles`.
- `radius_miles` (integer, optional, default 50) — Miles around `zip`. Ignored unless `zip` is set.
- `shipping_offered` (boolean, optional, default false) — Only lots whose auction house offers shipping.
- `page` (integer, optional, default 1) — 1-based page. HiBid serves at most 10,000 lots per query (1,000 on the archive), so the last reachable page is that cap divided by max_results.
- `max_results` (integer, optional, default 25) — Rows per page, 1-100. HiBid's own ceiling is 100: asking for 200 returns 100.

**Returns:** {query, status, total_available, total_is_capped, page, page_count, results[]} — each with auction_id, url, catalog_url, name, lot_count, matching_lot_count, currency, bid_open_at_local, bid_close_at_local, location{}, buyer_premium, terms{}, auction_house{}.

**Example request body:**
```json
{
  "query": "estate",
  "max_results": 10
}
```

### POST https://api.reefapi.com/hibid/v1/houses — 1 credit
HiBid's auction-house directory: id, trading name, street, town, state/province, postcode and country. Search by name fragment or by state. The ids are the ones that appear as `auction_house.id` on every lot.

**Parameters:**
- `name` (string, optional) — Name fragment, e.g. 'estate'. Matched as a wildcard.
- `state` (string, optional) — US state / Canadian province, TWO-LETTER CODE ONLY (TX, OH, BC). HiBid answers zero rows for a spelled-out name, so a name is rejected here with the reason.
- `house_sort` (enum, optional, default "name") — Directory order. [one of: name, location]
- `page` (integer, optional, default 1) — 1-based page. HiBid serves at most 10,000 lots per query (1,000 on the archive), so the last reachable page is that cap divided by max_results.
- `max_results` (integer, optional, default 25) — Rows per page, 1-100. HiBid's own ceiling is 100: asking for 200 returns 100.

**Returns:** {name, state, total_available, page, page_count, results[]} — each {house_id, name, street, city, state, postal_code, country}.

**Example request body:**
```json
{
  "name": "estate",
  "max_results": 10
}
```

### POST https://api.reefapi.com/hibid/v1/categories — 1 credit
HiBid's full category tree — the ids the `category_id` filter takes, with their parents, children and URL paths. Measured: 18 roots, 1,135 nodes.

**Parameters:** none

**Returns:** {root_count, node_count, categories[]} with {id, name, full_name, url_path, parent_id, children[]} per node.

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=hibid
- Human docs page: https://reefapi.com/docs/hibid
- Overview page: https://reefapi.com/hibid-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt