1stDibs API & Scraper
The 1stDibs API turns 1stdibs.com, the marketplace where vetted antique, vintage and contemporary design dealers consign furniture, lighting, fine art, fine jewellery and watches, into clean JSON in four actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search takes either a free-text query or a category path such as furniture/seating/lounge-chairs, jewelry/rings or art/paintings, and returns the item id, title, URL, the dealer's USD list price with 1stDibs' own conversions into nine other currencies, the creation date, the designer or artist when one is credited, height, width and depth in inches, the dealer's company name and completed-order count, the country and town the piece ships from, and the photography. Filters cover period, style, material, place of origin, colour, price band, sale items, designer and ships-from region, with five sort orders. detail returns one item or up to ten in a single call, in full: the dealer's own description, the whole 1stDibs detail table including materials, style, period, date of manufacture, place of origin, condition with the dealer's condition notes, set size and both reference numbers, plus the per-vertical rows the site publishes for that department - metal, stone, stone cut, weight and ring size on jewellery, medium and framing on art, production time, voltage and lampshade on lighting - the shipping quote per destination region, the SKU, the six-month listing-view count, and the price cross-checked against a second, independently published figure. filters returns every filter 1stDibs offers for a scope with its live option list and per-option count, which is where the filter values come from and which doubles as the category browser. seller returns one dealer's storefront: their inventory in the same row shape plus the dealer's identity and completed-order count. Verification on 2026-10-06 ran 200 search rows across four departments and eight categories: item id, URL, title, price, currency, dealer, ships-from country and category were present on 200 of 200, and no field carried HTML or escaped entities. Prices are the dealer's list price in USD; when a dealer withholds the figure the price comes back null with price_status saying so, never a zero. No 1stDibs account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
On 1stDibs a filter is not a query parameter you invent, and a missing price is not a zero
1stDibs decides what a filter means by where it sits in its own URL grammar, and that grammar is not symmetric. A value the site does not recognise is not rejected - it is dropped, and the full category comes back looking like a successful answer. This API translates every filter into the shape the site actually honours, then checks the site's own echo of what it applied before returning a single row. A filter the site ignored becomes a clear error naming the filter, never a quietly wrong result set. The same discipline covers price: a dealer who withholds the figure gets price null and price_status upon_request, so a withheld price can never be read as free.
| Request on lounge chairs (18,969 unfiltered, measured 2026-10-06) | What 1stDibs returned | What this API does |
|---|---|---|
| period 20th-century | 12,991 items, filter applied | Returned, with the filter echoed back in applied_filters |
| style art-deco | 672 items, filter applied | Returned |
| price_min 1000, price_max 5000 | 9,151 items; every row checked was inside the band | Returned, with the band in applied_filters |
| location france-europe | 517 items; 10 of 10 rows shipped from France | Returned, and the rows carry the country so you can check it yourself |
| an unrecognised filter value | 18,969 items - the whole category, with HTTP 200 | Refused with INVALID_PARAM naming the filter, so you never receive the unfiltered set by accident |
| period together with a designer filter | The designer applied, the period silently dropped | Refused, with the reason, because the answer would have been wrong |
| page 122 at 50 per page | No rows, and the site says the page does not exist | page_exists false and last_reachable_page, so a paginating client stops instead of looping |
Counts are from one minute on 2026-10-06 and move with the dealers' stock. The reachable window ends 6,000 items into any one query - at 200 per page that is 6,200 items - so deep inventory is reached by narrowing the search, which is what last_reachable_page is for.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/1stdibs/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"category": "furniture/seating/lounge-chairs",
"max_results": 10
}
}{
"ok": true,
"meta": {
"api": "1stdibs",
"endpoint": "search",
"mode": "live",
"latency_ms": 579.7,
"record_count": 10,
"bytes": 21840,
"cache_hit": false,
"completeness_pct": 100,
"stop_reason": "limit_reached",
"uri_ref": "/furniture/seating/lounge-chairs/",
"priced_rows": 10,
"upon_request_rows": 0,
"charged_credits": 1,
"version": "1.0.0",
"request_id": "9388fe2a76174833",
"queue_ms": 1.8,
"fetched_at": "2026-10-06T14:47:16.686Z"
},
"data": {
"query": null,
"category": "furniture/seating/lounge-chairs",
"total_available": 18966,
"page": 1,
"page_size": 10,
"page_exists": true,
"last_reachable_page": 601,
"has_more": true,
"sort": "recommended",
"page_kind": "browse",
"search_term_used": null,
"page_title": "Antique and Vintage Lounge Chairs - 18,966 For Sale at 1stDibs",
"page_heading": "Lounge Chairs",
"applied_filters": [
{
"name": "categoryL1",
"label": "Category",
"values": [
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]"
}
]
},
{
"name": "categoryL2",
"label": "Category",
"values": [
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]"
}
]
},
{
"name": "categoryL3",
"label": "Category",
"values": [
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]"
}
]
}
],
"results": [
{
"item_id": "f_52078502",
"url": "https://www.1stdibs.com/furniture/seating/lounge-chairs/pair-of-austrian-art-deco-lounge-chairs-mahogany/id-f_52078502/",
"title": "Pair of Austrian Art Deco Lounge Chairs in Mahogany",
"vertical": "furniture",
"category_code": "F_SEA_LOU",
"category_path": "furniture/seating/lounge-chairs",
"category_url": "https://www.1stdibs.com/furniture/seating/lounge-chairs/",
"price": 27500,
"currency": "USD",
"price_status": "published",
"price_is_upon_request": false,
"price_type": "RETAIL",
"discount_percent": null,
"price_quantity_note": "/ set",
"converted_prices": {
"USD": 27500,
"GBP": 21215.28,
"EUR": 24996.76,
"CAD": 40010.94,
"AUD": 40231.13,
"CHF": 23314.91,
"MXN": 506849.17,
"NOK": 269096.47,
"SEK": 281619.05,
"DKK": 186814.82
},
"is_sold": false,
"is_available": true,
"is_on_hold": false,
"is_new_listing": false,
"is_multi_sku": false,
"creation_date": "1920s",
"creators": null,
"seller": {
"seller_id": "f_9331",
"name": "MORENTZ",
"order_count": 5722,
"is_distinguished": true
},
"ships_from_country": "Netherlands",
"ships_from_city": "Waalwijk",
"dimensions_in": {
"height": 32.29,
"width": 32.68,
"depth": 32.68,
"length": null,
"diameter": null
},
"images": [
"https://a.1stdibscdn.com/pair-of-austrian-art-deco-lounge-chairs-in-mahogany-for-sale/f_9331/f_520785021789743887713/tmp_image_master.JPEG",
"https://a.1stdibscdn.com/pair-of-austrian-art-deco-lounge-chairs-in-mahogany-for-sale-picture-2/f_9331/f_520785021789743892511/tmp_image_master.JPEG",
"https://a.1stdibscdn.com/pair-of-austrian-art-deco-lounge-chairs-in-mahogany-for-sale-picture-3/f_9331/f_520785021789743897841/tmp_image_master.JPEG"
]
},
{
"item_id": "f_51951972",
"url": "https://www.1stdibs.com/furniture/seating/lounge-chairs/1930s-extremely-grand-danish-lounge-chair-reupholstered-yellow-mohair/id-f_51951972/",
"title": "1930s Extremely Grand Danish Lounge Chair Reupholstered in Yellow Mohair",
"vertical": "furniture",
"category_code": "F_SEA_LOU",
"category_path": "furniture/seating/lounge-chairs",
"category_url": "https://www.1stdibs.com/furniture/seating/lounge-chairs/",
"price": 24500,
"currency": "USD",
"price_status": "published",
"price_is_upon_request": false,
"price_type": "RETAIL",
"discount_percent": null,
"price_quantity_note": null,
"converted_prices": {
"USD": 24500,
"GBP": 18900.89,
"EUR": 22269.84,
"CAD": 35646.11,
"AUD": 35842.28,
"CHF": 20771.46,
"MXN": 451556.53,
"NOK": 239740.49,
"SEK": 250896.98,
"DKK": 166435.02
},
"is_sold": false,
"is_available": true,
"is_on_hold": false,
"is_new_listing": false,
"is_multi_sku": false,
"creation_date": "1930s",
"creators": null,
"seller": {
"seller_id": "f_9331",
"name": "MORENTZ",
"order_count": 5722,
"is_distinguished": true
},
"ships_from_country": "Netherlands",
"ships_from_city": "Waalwijk",
"dimensions_in": {
"height": 37.41,
"width": 38.59,
"depth": 40.16,
"length": null,
"diameter": null
},
"images": [
"https://a.1stdibscdn.com/1930s-extremely-grand-danish-lounge-chair-reupholstered-in-yellow-mohair-for-sale/1121189/f_519519721789634304495/51951972_datamatics.jpeg",
"https://a.1stdibscdn.com/1930s-extremely-grand-danish-lounge-chair-reupholstered-in-yellow-mohair-for-sale-picture-2/f_9331/f_519519721789386634948/tmp_image_master.JPEG",
"https://a.1stdibscdn.com/1930s-extremely-grand-danish-lounge-chair-reupholstered-in-yellow-mohair-for-sale-picture-3/f_9331/f_519519721789386638786/tmp_image_master.JPEG"
]
},
{
"item_id": "f_51951792",
"url": "https://www.1stdibs.com/furniture/seating/lounge-chairs/pair-of-lounge-chairs-wood-sand-colored-fabric-1940s/id-f_51951792/",
"title": "Pair of Lounge Chairs in Wood and Sand-Colored Fabric, 1940s",
"vertical": "furniture",
"category_code": "F_SEA_LOU",
"category_path": "furniture/seating/lounge-chairs",
"category_url": "https://www.1stdibs.com/furniture/seating/lounge-chairs/",
"price": 5850,
"currency": "USD",
"price_status": "published",
"price_is_upon_request": false,
"price_type": "RETAIL",
"discount_percent": null,
"price_quantity_note": "/ set",
"converted_prices": {
"USD": 5850,
"GBP": 4513.07,
"EUR": 5317.49,
"CAD": 8511.42,
"AUD": 8558.26,
"CHF": 4959.72,
"MXN": 107820.64,
"NOK": 57244.16,
"SEK": 59908.05,
"DKK": 39740.61
},
"is_sold": false,
"is_available": true,
"is_on_hold": false,
"is_new_listing": false,
"is_multi_sku": false,
"creation_date": "1940s",
"creators": null,
"seller": {
"seller_id": "f_9331",
"name": "MORENTZ",
"order_count": 5722,
"is_distinguished": true
},
"ships_from_country": "Netherlands",
"ships_from_city": "Waalwijk",
"dimensions_in": {
"height": 32.88,
"width": 27.76,
"depth": 32.29,
"length": null,
"diameter": null
},
"images": [
"https://a.1stdibscdn.com/pair-of-lounge-chairs-in-wood-and-sand-colored-fabric-1940s-for-sale/1121189/f_519517921789634291265/51951792_datamatics.jpeg",
"https://a.1stdibscdn.com/pair-of-lounge-chairs-in-wood-and-sand-colored-fabric-1940s-for-sale-picture-2/f_9331/f_519517921789385004616/tmp_image_master.JPEG",
"https://a.1stdibscdn.com/pair-of-lounge-chairs-in-wood-and-sand-colored-fabric-1940s-for-sale-picture-3/f_9331/f_519517921789385008898/tmp_image_master.JPEG"
]
}
]
}
}What the 1stDibs API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search 1stDibs — antique and vintage furniture, lighting, fine art, fine jewellery, watches and fashion from vetted trade dealers worldwide. You must give EITHER `query` (free text, the site's own search) OR `category` (a category path such as 'furniture/seating/lounge-chairs'); `vertical` is a shorthand for the latter. Every other parameter is an optional filter and each one is verified against the source's own echo of what it applied, so a value the site does not know fails loudly instead of quietly returning the whole category. Prices are the dealer's USD list price; a row whose seller withholds the figure comes back with `price: null` and `price_status: "upon_request"` — never a zero. | Pricing teams call search to search 1stDibs. | query, category, vertical, style, period, ... |
| detail | One item — or up to ten in a single upstream call — in full: the dealer's description, the whole 1stDibs detail table (dimensions, materials and techniques, style, period, date of manufacture, place of origin, condition and condition notes, set size, reference numbers), the dealer's own shipping quote per destination region, the seller's profile numbers, the SKU, the six-month listing-view count, and the price cross-checked against the schema.org offer block the site publishes separately. When the two price witnesses disagree the disagreement is published in `price_mismatch`, not hidden. | Marketplace operators call detail to get one item. | item |
| filters | Every filter 1stDibs offers for a given scope, with its live option list and per-option result count — the only published place the filter SLUGS exist, so this is how you learn the values `search` takes. The facet set is category-dependent: art adds Orientation, Size, Art Subject and Frame Included, furniture adds Number in Set and Dimensions. It also returns the child categories of whatever level you ask about, so it doubles as the category browser. Takes the same `query`/`category` pair as `search`. | Catalog enrichment teams call filters to get every filter 1stDibs offers for a given scope, with its live option list and per-option resul…. | query, category, vertical, style, period, ... |
| seller | One dealer's storefront: their live inventory with the same row shape as `search`, plus the dealer's identity and the numbers 1stDibs publishes about them (company name, completed-order count, recognised-dealer flag, shipping country). Takes the storefront slug from a /dealers/<slug>/ URL. | Retail analysts call seller to get one dealer's storefront. | seller, sort, page, max_results |
Call search from your stack
curl -X POST https://api.reefapi.com/1stdibs/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"category":"furniture/seating/lounge-chairs","max_results":10}'import requests
r = requests.post(
"https://api.reefapi.com/1stdibs/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"category": "furniture/seating/lounge-chairs",
"max_results": 10
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/1stdibs/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"category": "furniture/seating/lounge-chairs",
"max_results": 10
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.1stdibs.search with {"category":"furniture/seating/lounge-chairs","max_results":10}.Who uses this API and why
- Antique and design dealers price stock by reading comparable live inventory per category, period, style and material, with every figure in the dealer's own listed currency.
- Interior designers and procurement teams build sourcing shortlists filtered by dimensions, place of origin, ships-from region and price band, then pull the full detail table for the pieces that fit the room.
- Auction houses and appraisers compare a lot against the live retail asking prices of the same designer, period and material before setting an estimate.
- Marketplace and resale platforms enrich their own catalogues with the structured attribute table 1stDibs publishes per department - materials, period, origin, condition, dimensions - from an item URL.
- Dealer-relations and competitive teams track one gallery's storefront over time: how many pieces are live, what they ask, and where the gallery ships from.
Questions developers ask before integrating
Which departments and categories does it cover?
All four 1stDibs departments and their category trees: furniture (seating, tables, lighting, rugs, storage, decorative objects and more), art (paintings, prints and works on paper, photography, sculpture, mixed media), jewelry (rings, necklaces, earrings, watches) and fashion (handbags, clothing, accessories). You pass the category path the site uses in its own URL, for example furniture/seating/lounge-chairs or art/prints-works-on-paper, and the filters action lists the child categories of any level with their live counts so you never have to guess a path.
What currency are the prices in?
1stDibs lists in US dollars and that is what price and currency carry. Alongside it, converted_prices republishes 1stDibs' own conversions into GBP, EUR, CAD, AUD, CHF, MXN, NOK, SEK and DKK exactly as the site publishes them. Nothing is converted by this API and no exchange rate of ours is applied - the amount and the currency code are always read as one pair, so a figure can never be relabelled.
What happens when a dealer does not publish a price?
You get price null and price_status upon_request, plus price_is_upon_request true, which is 1stDibs' own flag for a seller who withholds the figure. A third state, not_published, covers an item with no amount and no flag. A withheld price is never returned as 0 and never guessed. Across 1,500 rows read on 2026-10-06 every item on the public browse and search surface did carry a USD amount, so the withheld case is rare - which is exactly why it has its own value instead of collapsing into a number.
How much detail does one item return?
The dealer's full description plus the entire 1stDibs detail table, and that table is different in every department. A chair returns materials and techniques, style, period, date of manufacture, place of origin, condition with the dealer's condition notes, set size, seller location and both the dealer's and 1stDibs' reference numbers. A ring returns metal, stone, stone cut, weight and ring size instead. A painting returns medium, framing and movement. Everything the site prints for that item is published whole in details and in attributes, so a department we did not sample still comes through complete. You also get the shipping quote per destination region, the SKU and quantity, and the six-month listing-view count.
Can I get sold prices or auction results?
No. 1stDibs serves a sold archive only to signed-in buyers; logged out it returns nothing, and this API does not offer an endpoint that would come back empty. Dealer trade pricing and make-an-offer figures are behind a buyer account too. For auction results, ReefAPI's catawiki and auctionet APIs return sold and unsold lots with hammer prices.
Can I pull one dealer's whole inventory?
Yes. The seller action takes a dealer's storefront slug and returns their live inventory in the same row shape as search, plus the dealer's company name, completed-order count, recognised-dealer status and the country and town they ship from. A dealer who is listed but currently has nothing for sale comes back with has_live_inventory false rather than an error, and a slug 1stDibs does not know returns NOT_FOUND.
Is the price verified against anything?
Yes. The detail action reads a second figure 1stDibs publishes separately for the same item and compares the two. When they agree nothing is added; when they disagree the disagreement itself is published in price_mismatch with both numbers, rather than one of them being chosen quietly. The same check covers availability. On the 16 items verified on 2026-10-06 the two figures agreed on 16 of 16.
What does 1stDibs NOT publish without an account?
No trade price and no make-an-offer figure, no sold archive, no item-level reviews or ratings, no dealer phone or street address, and no stock figure beyond the SKU quantity. Dimensions exist for furniture, art and fashion but not for most rings, which the site simply does not measure - those come back null rather than invented. The period LABEL is only on the item detail; a search row carries the dealer's creation date instead, because 1stDibs leaves the period field empty on every search row we measured.
What is the 1stDibs API?
1stDibs API is a ReefAPI endpoint group for dealer-consigned antique, vintage and contemporary design: furniture, lighting, fine art, jewellery and watches with usd prices, period, materials, dimensions, dealer and shipping. It returns live JSON through POST requests under /1stdibs/v1.
Is the 1stDibs API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. 1stDibs calls use the same shared credit balance as every other ReefAPI engine.
Do I need a 1stDibs login or account?
No login to 1stDibs is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the 1stDibs data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the 1stDibs API use?
1stDibs actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call 1stDibs from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call 1stdibs actions with the same key, credit pool and JSON envelope used by normal REST requests.