Luxury antique, vintage and design listings as JSON, priced in the dealer's own currency
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.
4 active endpoints, on 1 and 2 credit tiers.
- POST/1stdibs/v1/search
- POST/1stdibs/v1/detail
- POST/1stdibs/v1/filters
- POST/1stdibs/v1/seller
What 1stDibs endpoints does ReefAPI ship?
4 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
1stDibs API
4 of 4 endpoints, ready to run
1stDibs listings by category or keyword: item id, URL, title, the dealer's USD price with 1stDibs' own conversions, creation date, designer, dimensions in inches, dealer, ships-from country and photography.
// Press "Try it" and this pane shows exactly what the // live site returned this second — including an empty // result, if that is the truth. No key, no account.
How the 1stDibs API works
1stDibs is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 438 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
From a department to a priced, fully described piece in three calls
1stDibs organises everything by category path and filter slug, and both come from the site itself. Read them first, then search, then pull the detail - and pull it for ten items at once, because detail is batched.
Returns the child categories of that level with live counts, and every filter the department serves with its option slugs: style, period, material, origin, colour, price bands, ships-from region and designer. This is where the values for the next call come from, so nothing is guessed.
Each row carries the item id, the dealer's USD price with 1stDibs' own conversions, the creation date, height, width and depth in inches, the dealer and the ships-from country. applied_filters echoes back exactly what 1stDibs applied, so you can see the filter bit.
Returns the dealer's description, the full detail table for that department, condition and condition notes, both reference numbers, the shipping quote per destination region, the SKU and the six-month view count - and flags any disagreement between the two prices 1stDibs publishes for the item.
A priced, dated, measured and sourced row per piece with the dealer named, ready to compare against your own stock or an auction estimate. Ten items of full detail cost one call, so the batched shape is the cheap one.
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}'{
"ok": true,
"data": { … },
"meta": {
"api": "1stdibs",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Markets, currency and ids - measured 2026-10-06
1stDibs is one global marketplace rather than a set of country sites: dealers all over the world list into the same catalogue and ship internationally, and the price is quoted in US dollars wherever the dealer sits. There is no country parameter, because the catalogue is not partitioned by one. What varies is where a piece ships FROM, and that is a filter and a field, not a market.
One global catalogue, four departments: furniture, art, jewelry and fashion. Dealers are worldwide - 21 different ships-from countries appeared in a single 200-row sample across ten categories.
There is none, and that is deliberate. Where a piece ships from is the location filter (continental-us, europe, france-europe, england-united-kingdom and more, read live from the filters action) and every row carries ships_from_country and ships_from_city. Place of origin - where the piece was MADE - is a separate filter and a separate field.
Pinned to USD: 1stDibs lists in dollars, so price and currency are always the dealer's USD figure. converted_prices republishes 1stDibs' own conversions into nine more currencies untouched. On 200 rows across ten categories the amount and its currency code agreed with each other on 200 of 200, and on the 10 items pulled in full the price matched the second figure 1stDibs publishes separately on 10 of 10.
Stable and globally unique, with a department prefix: f_ furniture, a_ art, j_ jewelry, v_ watches. Search to detail and back returned the identical id, same string type, on 8 of 8 ids spanning all four prefixes. The id is also the /id-<id>/ segment of the item URL, so a URL can be passed straight in.
The reachable window ends 6,000 items into any one query - 6,200 at 200 per page. Past it 1stDibs says the page does not exist, and the response says so too: page_exists false, plus last_reachable_page and has_more. Deep inventory is reached by narrowing the search, not by paging further.
No sold archive, no trade price, no make-an-offer figure, no item reviews, no dealer phone or address, and no stock figure beyond the SKU quantity. Dimensions are published for furniture, art and fashion but not for most rings.
What people build with 1stDibs
The jobs this data is most often used for.
endpoints
credits per call
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.
What 1stDibs data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 438 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up 1stDibs.
Get a free key →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.
191 E-commerce & Marketplaces APIs on the same key
One key, one credit pool, one response envelope. If you are pulling 1stDibs, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 437 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-10-06.