# Catawiki API scraper - Europe's weekly online auctions (watches, art, jewellery, classic cars, coins, wine, collectibles): lot search with live bids, full lot records with expert estimate, reserve status, Buyer Protection fee and shipping per country, bid history, auction and category listings. EUR, GBP or USD in 18 languages. No account, no browser.

> Search open Catawiki lots by keyword: lot id, title, image, the current bid in EUR, GBP or USD, whether anyone has bid, closing time, reserve price set and met, buy-now price, free shipping and the auction id. Filter by category, reserve, free shipping, seller country and closing day; sort by relevance, ending soon or newest. Unrelated padding shown for keywords with no results is dropped and counted.
> ReefAPI engine `catawiki` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/catawiki/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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /catawiki/v1/search — 1 credit
Search open Catawiki lots by keyword: lot id, title, image, the current bid in EUR, GBP or USD, whether anyone has bid, closing time, reserve price set and met, buy-now price, free shipping and the auction id. Filter by category, reserve, free shipping, seller country and closing day; sort by relevance, ending soon or newest. Unrelated padding shown for keywords with no results is dropped and counted.

**Parameters:**
- `query` (string, required) — Keyword, in any language Catawiki supports (typos such as 'rolx' are corrected by the site).
- `category_id` (string, optional) — Only lots in these Catawiki categories (numbers such as 343 Rolex Watches; `categories` lists them). Comma-separated.
- `page` (integer, optional, default 1) — Result page, 1-based. A page past the end returns an empty list.
- `per_page` (integer, optional, default 24) — Lots per page, 1-100 (default 24, as on the site).
- `sort` (enum, optional, default "relevance") — Order. Only orderings measured to change the results are accepted. [one of: relevance, ending_soon, newest]
- `reserve` (enum, optional) — Only lots with, or without, a reserve price. [one of: with_reserve, no_reserve]
- `free_shipping` (boolean, optional) — Only lots with free shipping everywhere.
- `seller_country` (string, optional) — Only lots whose seller is in these countries (two-letter codes, comma-separated).
- `closing_date` (string, optional) — Only lots closing on these days (YYYY-MM-DD, comma-separated).
- `language` (enum, optional, default "en") — Language of titles, descriptions, specifications and category names (Catawiki's own translations). Lots are the same in every language. [one of: en, nl, de, fr, it, es, pt, da, sv, no, fi, pl, hu, ro, el, ja, zh-Hans, zh-Hant]
- `currency` (enum, optional, default "EUR") — Currency for bids, estimates, fees and shipping. Catawiki converts from EUR itself. [one of: EUR, GBP, USD]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).
- `include_fallback_results` (boolean, optional, default false) — When Catawiki finds nothing for a keyword it shows unrelated 'you may also like' lots. They are dropped by default and counted; true returns them in `fallback_results`.

**Returns:** lots[]{lot_id, title, subtitle, url, image, thumbnail, auction_id, currency, current_bid (number, null while nobody has bid; excludes fee and shipping), has_bids, status (open|closed), is_sold, sold_price (only when sold), reserve_price_set, reserve_price_met (null when no reserve), buy_now_price_eur, buy_now_available, free_shipping, start_time, end_time, favorite_count, explicit_content, bid_state (ok|unavailable), rating (null), review_count (null)}, count, total_results, page, has_more, fallback_results_dropped, fallback_results[] (only with include_fallback_results), corrected_query, query, filters{}

**Example request body:**
```json
{
  "query": "rolex",
  "per_page": 24
}
```

### POST /catawiki/v1/product/detail — 1 credit
One Catawiki lot in full, open or closed: title, description, every image, specifications (brand, model, condition, year…), the expert or retail estimate, the current or final bid, bid count, next minimum bid, reserve met, sold or not, buy-now price, the Buyer Protection fee and the fee on the current bid, shipping rates per country (and the total if won now for your country), delivery time, the seller (pro or private, score, feedback counts, objects sold, country), the curating experts and the last 10 bids.

**Parameters:**
- `lot_id` (integer, required) — Catawiki lot id - the number in /l/<id>-<slug>. A full lot URL works.
- `shipping_country` (string, optional) — Two-letter country code to quote shipping and the total cost for. Default: the shipping rates for every country are returned without a total.
- `language` (enum, optional, default "en") — Language of titles, descriptions, specifications and category names (Catawiki's own translations). Lots are the same in every language. [one of: en, nl, de, fr, it, es, pt, da, sv, no, fi, pl, hu, ro, el, ja, zh-Hans, zh-Hant]
- `currency` (enum, optional, default "EUR") — Currency for bids, estimates, fees and shipping. Catawiki converts from EUR itself. [one of: EUR, GBP, USD]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** item{lot_id, title, subtitle, url, language, status (open|closed), is_sold, currency, current_bid, last_bid, sold_price, bid_count, next_minimum_bid, reserve_price_met, close_to_reserve_price, buy_now_price, buy_now_price_eur, buy_now_available_until, experts_estimate{min, max, type (expert|retail), label}, buyer_protection_fee{percentage, fixed, currency}, buyer_protection_fee_amount (on current_bid, or on sold_price when sold), total_if_won_now (open lots with shipping_country), start_time, end_time, auction_id, category{id, url, level}, description, auto_translated_description, summary, specifications[]{name, value, specification_id, value_id}, attributes{brand, model, condition, gender, movement, material, country_of_origin, period, case_diameter, year}, images[], image, video_count, experts[]{id, name, bio}, seller{id, name, url, type (pro|private), is_top_seller, country{code, name}, city, score, score_scale, positive_count, neutral_count, negative_count, feedback_count, objects_sold, lots_in_auction, member_since, badges[], profile}, shipping{destination{code, name, price, available, currency}, rates[]{country_code, country, price, currency}, delivery_days{from, to}, combined_shipping_allowed, delivery_methods[], pickup_only, pickup_location, extra_insurance, payment_methods[]}, favorite_count, high_interest, explicit_content, recent_bids[], gtin (null), rating (null), review_count (null)}, auction{auction_id, title, url, status, start_time, close_time, closed_at, lot_count, themed, image}

### POST /catawiki/v1/lot/bids — 1 credit
The full bid history of one Catawiki lot, newest first: amount in EUR, GBP or USD, time, the bidder's public pseudonym and country, and how many bids that bidder has placed on Catawiki.

**Parameters:**
- `lot_id` (integer, required) — Catawiki lot id - the number in /l/<id>-<slug>. A full lot URL works.
- `currency` (enum, optional, default "EUR") — Currency for bids, estimates, fees and shipping. Catawiki converts from EUR itself. [one of: EUR, GBP, USD]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** lot_id, currency, bids[]{bid_id, amount, currency, time, bidder, bidder_country, bidder_total_bids, from_order}, count, highest_bid

### POST /catawiki/v1/auction/lots — 1 credit
Every lot of one Catawiki auction, open or already closed, with the auction's title, status and closing time and each lot's current or final bid, sold flag, reserve status and buy-now price - a closed auction is a list of real sale results.

**Parameters:**
- `auction_id` (integer, required) — Catawiki auction id - the number in /a/<id>-<slug>; every lot row returns it.
- `page` (integer, optional, default 1) — Result page, 1-based. A page past the end returns an empty list.
- `per_page` (integer, optional, default 24) — Lots per page, 1-100 (default 24, as on the site).
- `language` (enum, optional, default "en") — Language of titles, descriptions, specifications and category names (Catawiki's own translations). Lots are the same in every language. [one of: en, nl, de, fr, it, es, pt, da, sv, no, fi, pl, hu, ro, el, ja, zh-Hans, zh-Hant]
- `currency` (enum, optional, default "EUR") — Currency for bids, estimates, fees and shipping. Catawiki converts from EUR itself. [one of: EUR, GBP, USD]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** auction{auction_id, title, url, status, start_time, close_time, closed_at, lot_count, themed, image}, lots[]{lot_id, title, subtitle, url, image, thumbnail, auction_id, currency, current_bid (number, null while nobody has bid; excludes fee and shipping), has_bids, status (open|closed), is_sold, sold_price (only when sold), reserve_price_set, reserve_price_met (null when no reserve), buy_now_price_eur, buy_now_available, free_shipping, start_time, end_time, favorite_count, explicit_content, bid_state (ok|unavailable), rating (null), review_count (null)}, count, total_results, page, has_more

### POST /catawiki/v1/category/products — 1 credit
Browse the open lots of one Catawiki category with live bids, the same row fields as search, and the same reserve, free shipping, seller country and closing day filters and sorts.

**Parameters:**
- `category_id` (integer, required) — Catawiki category id - the number in /c/<id>-<slug>; `categories` lists them.
- `page` (integer, optional, default 1) — Result page, 1-based. A page past the end returns an empty list.
- `per_page` (integer, optional, default 24) — Lots per page, 1-100 (default 24, as on the site).
- `sort` (enum, optional, default "relevance") — Order. Only orderings measured to change the results are accepted. [one of: relevance, ending_soon, newest]
- `reserve` (enum, optional) — Only lots with, or without, a reserve price. [one of: with_reserve, no_reserve]
- `free_shipping` (boolean, optional) — Only lots with free shipping everywhere.
- `seller_country` (string, optional) — Only lots whose seller is in these countries (two-letter codes, comma-separated).
- `closing_date` (string, optional) — Only lots closing on these days (YYYY-MM-DD, comma-separated).
- `language` (enum, optional, default "en") — Language of titles, descriptions, specifications and category names (Catawiki's own translations). Lots are the same in every language. [one of: en, nl, de, fr, it, es, pt, da, sv, no, fi, pl, hu, ro, el, ja, zh-Hans, zh-Hant]
- `currency` (enum, optional, default "EUR") — Currency for bids, estimates, fees and shipping. Catawiki converts from EUR itself. [one of: EUR, GBP, USD]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).
- `include_sponsored` (boolean, optional, default false) — Catawiki can promote lots on category pages. They are dropped by default and counted in sponsored_dropped; true returns them with sponsored: true.

**Returns:** category{id, name, url, parent_id, level, auction_count, ancestors[]{id, name, level}}, lots[]{lot_id, title, subtitle, url, image, thumbnail, auction_id, currency, current_bid (number, null while nobody has bid; excludes fee and shipping), has_bids, status (open|closed), is_sold, sold_price (only when sold), reserve_price_set, reserve_price_met (null when no reserve), buy_now_price_eur, buy_now_available, free_shipping, start_time, end_time, favorite_count, explicit_content, bid_state (ok|unavailable), sponsored, rating (null), review_count (null)}, count, total_results, page, has_more, sponsored_dropped (count is organic rows)

### POST /catawiki/v1/categories — 1 credit
Catawiki's category tree one level at a time: id, name, parent, link and how many auctions each category is running.

**Parameters:**
- `level` (integer, optional, default 0) — Category tree level: 0 top categories (16), 1 categories (80), 2 sub-categories (~310).
- `parent_id` (integer, optional) — Only categories directly under this one.
- `language` (enum, optional, default "en") — Language of titles, descriptions, specifications and category names (Catawiki's own translations). Lots are the same in every language. [one of: en, nl, de, fr, it, es, pt, da, sv, no, fi, pl, hu, ro, el, ja, zh-Hans, zh-Hant]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** categories[]{id, name, url, parent_id, level, auction_count}, count, level

### POST /catawiki/v1/suggest — 1 credit
Catawiki's own keyword suggestions for the start of a search term.

**Parameters:**
- `query` (string, required) — The start of a keyword.
- `language` (enum, optional, default "en") — Language of titles, descriptions, specifications and category names (Catawiki's own translations). Lots are the same in every language. [one of: en, nl, de, fr, it, es, pt, da, sv, no, fi, pl, hu, ro, el, ja, zh-Hans, zh-Hant]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** query, suggestions[], count

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

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