# 1stDibs — luxury antique, vintage & design marketplace

> 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.
> ReefAPI engine `1stdibs` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/1stdibs/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/1stdibs/v1/search — 2 credits
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.

**Parameters:**
- `query` (string, optional) — Free-text search over the whole marketplace, exactly as the site's own search box takes it (e.g. 'eames lounge chair', 'cartier watch', 'murano chandelier'). Either `query` or `category` is required — see the action description.
- `category` (string, optional) — A 1stDibs category path, 1-4 levels, as it appears in the site's own URL: 'furniture', 'furniture/seating', 'furniture/seating/lounge-chairs', 'jewelry/rings', 'art/paintings', 'furniture/lighting/chandeliers-pendant-lights'. Call the `filters` action to read the child categories of any level with their live counts. Either `query` or `category` is required.
- `vertical` (enum, optional) — Shorthand for the top-level category when you do not want to name a path. Ignored when `category` is given. [one of: furniture, art, jewelry, fashion]
- `style` (string, optional) — Design-style filter, by the slug 1stDibs uses in its own URLs ('art-deco', 'mid-century-modern', 'abstract', 'louis-xvi'). The available styles differ per category — read them from the `filters` action. A style the category does not have is rejected rather than silently ignored.
- `period` (string, optional) — Period filter, by the site's own slug: '18th-century-and-earlier', '19th-century', '20th-century', '21st-century-and-contemporary', or a decade like '1920s' … '1990s'. Read the live list from `filters`.
- `material` (string, optional) — Material / medium filter, by the site's own slug ('mahogany', 'brass', 'oil-paint', 'canvas', '18k-gold'). Read the live list from `filters`; for art this facet is labelled 'Medium'.
- `origin` (string, optional) — Place-of-origin filter — where the piece was MADE — by the site's own slug ('austrian', 'italian', 'french', 'danish'). This is not the same thing as `location`, which is where the dealer ships it from.
- `creator` (string, optional) — Restrict to one designer, maker, house or artist, by the site's own slug ('vahe-yeremyan', 'gio-ponti', 'hermes'). The `filters` action publishes the slugs with their counts for whatever scope you ask about.
- `location` (string, optional) — Ships-from filter, by the site's own slug ('continental-us', 'europe', 'france-europe', 'england-united-kingdom', 'new-york-usa'). This is the dealer's location, not the place of manufacture. Read the live list from `filters`.
- `color` (string, optional) — Dominant-colour filter, by the site's own slug ('blue', 'gray', 'brown', 'gold'). 1stDibs derives it from the photography, so it is the site's judgement, not the dealer's.
- `price_min` (number, optional) — Lowest USD price to include. 1stDibs lists in USD, so this filter is applied in USD by the source itself.
- `price_max` (number, optional) — Highest USD price to include, in USD. Combine with `price_min` for a band; either one alone works as an open-ended bound.
- `on_sale` (boolean, optional, default false) — True returns only items the dealer has marked down (the site's 'Sale Items' facet). Measured: 1,800 of 18,969 lounge chairs.
- `sort` (enum, optional, default "recommended") — Row order, using 1stDibs' own sort options. 'price-high' and 'price-low' rank by the USD list price. [one of: recommended, newest, price-high, price-low, popular]
- `page` (integer, optional, default 1) — 1-based page. 1stDibs serves a window that ends at offset 6,000: the last reachable page is 6000/max_results + 1. Past it the source itself answers `page_exists: false` with no rows — narrow the query to reach deeper stock.
- `max_results` (integer, optional, default 50) — Rows per page, 1-200. The source accepts more, but 200 keeps one call small and fast (measured ~9 KB, ~0.8 s).

**Returns:** {query, category, total_available, page, page_size, page_exists, last_reachable_page, has_more, sort, page_kind, applied_filters[], page_title, results[]} — each result has item_id, url, title, vertical, category_code, category_path, category_url, price, currency, price_status, price_is_upon_request, price_type, discount_percent, price_quantity_note, converted_prices, is_sold, is_available, is_on_hold, is_new_listing, is_multi_sku, creation_date, creators[], seller{}, ships_from_country, ships_from_city, dimensions_in{}, images[].

**Example request body:**
```json
{
  "category": "furniture/seating/lounge-chairs",
  "max_results": 10
}
```

### POST https://api.reefapi.com/1stdibs/v1/detail — 1 credit
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.

**Parameters:**
- `item` (string, required) — A 1stDibs item id as the site prints it ('f_52078502' for furniture, 'a_18430382' art, 'j_30657952' jewelry, 'v_29932282' watches), or any 1stdibs.com item URL — the id is read out of the '/id-<id>/' segment. Up to 10 ids, comma-separated, are fetched in ONE upstream call.

**Returns:** {requested, found, missing[], items[]} — each item is the search row plus description, condition, condition_notes, materials[], styles[], periods[], origins[], date_of_manufacture, set_size, reference_numbers[], attributes{}, dimensions_display[], seller_location, breadcrumbs[], details[], shipping[], sku{}, listing_views_6m, schema_org_offer{} and price_mismatch.

**Example request body:**
```json
{
  "item": "f_52078502"
}
```

### POST https://api.reefapi.com/1stdibs/v1/filters — 1 credit
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`.

**Parameters:**
- `query` (string, optional) — Free-text search over the whole marketplace, exactly as the site's own search box takes it (e.g. 'eames lounge chair', 'cartier watch', 'murano chandelier'). Either `query` or `category` is required — see the action description.
- `category` (string, optional) — A 1stDibs category path, 1-4 levels, as it appears in the site's own URL: 'furniture', 'furniture/seating', 'furniture/seating/lounge-chairs', 'jewelry/rings', 'art/paintings', 'furniture/lighting/chandeliers-pendant-lights'. Call the `filters` action to read the child categories of any level with their live counts. Either `query` or `category` is required.
- `vertical` (enum, optional) — Shorthand for the top-level category when you do not want to name a path. Ignored when `category` is given. [one of: furniture, art, jewelry, fashion]
- `style` (string, optional) — Design-style filter, by the slug 1stDibs uses in its own URLs ('art-deco', 'mid-century-modern', 'abstract', 'louis-xvi'). The available styles differ per category — read them from the `filters` action. A style the category does not have is rejected rather than silently ignored.
- `period` (string, optional) — Period filter, by the site's own slug: '18th-century-and-earlier', '19th-century', '20th-century', '21st-century-and-contemporary', or a decade like '1920s' … '1990s'. Read the live list from `filters`.
- `material` (string, optional) — Material / medium filter, by the site's own slug ('mahogany', 'brass', 'oil-paint', 'canvas', '18k-gold'). Read the live list from `filters`; for art this facet is labelled 'Medium'.
- `origin` (string, optional) — Place-of-origin filter — where the piece was MADE — by the site's own slug ('austrian', 'italian', 'french', 'danish'). This is not the same thing as `location`, which is where the dealer ships it from.
- `creator` (string, optional) — Restrict to one designer, maker, house or artist, by the site's own slug ('vahe-yeremyan', 'gio-ponti', 'hermes'). The `filters` action publishes the slugs with their counts for whatever scope you ask about.
- `location` (string, optional) — Ships-from filter, by the site's own slug ('continental-us', 'europe', 'france-europe', 'england-united-kingdom', 'new-york-usa'). This is the dealer's location, not the place of manufacture. Read the live list from `filters`.

**Returns:** {query, category, total_available, filter_count, categories{}, filters[]} — each filter has name, label, value_count and values[] of {value, label, count, linkable, currency, hex_code}. `name` is exactly the `search` parameter it feeds where one exists.

**Example request body:**
```json
{
  "category": "furniture/seating/lounge-chairs"
}
```

### POST https://api.reefapi.com/1stdibs/v1/seller — 2 credits
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.

**Parameters:**
- `seller` (string, required) — A dealer's storefront slug as it appears in a 1stdibs.com/dealers/<slug>/ URL (e.g. 'morentz'), or the full storefront URL. Returns that dealer's live inventory plus the dealer's own profile numbers.
- `sort` (enum, optional, default "recommended") — Row order, using 1stDibs' own sort options. 'price-high' and 'price-low' rank by the USD list price. [one of: recommended, newest, price-high, price-low, popular]
- `page` (integer, optional, default 1) — 1-based page. 1stDibs serves a window that ends at offset 6,000: the last reachable page is 6000/max_results + 1. Past it the source itself answers `page_exists: false` with no rows — narrow the query to reach deeper stock.
- `max_results` (integer, optional, default 50) — Rows per page, 1-200. The source accepts more, but 200 keeps one call small and fast (measured ~9 KB, ~0.8 s).

**Returns:** {seller_slug, seller{seller_id, name, order_count, is_distinguished, ships_from_country}, total_available, has_live_inventory, page, page_size, page_exists, has_more, results[]} — rows identical to `search`.

**Example request body:**
```json
{
  "seller": "morentz",
  "max_results": 10
}
```

## 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=1stdibs
- Human docs page: https://reefapi.com/docs/1stdibs
- Overview page: https://reefapi.com/1stdibs-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt