Chairish API & Scraper
The Chairish API turns chairish.com, the US marketplace where independent dealers and makers consign vintage, antique and used design, 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 is scoped by free text, by a Chairish collection path such as floor-lamps, rings or rugs/persian, by a brand or designer storefront such as herman-miller, or by one of the site's own keyword pages, and returns the item id, title, URL, the USD price with the pre-markdown price and the discount percentage when the dealer has marked a piece down, the condition, the brand, the colour, the materials, the height, width and depth in inches, the dealer id with their city and state, the shipping type and the countries the piece ships to, the dealer's own description and every photo. Filters cover style, category, colour, price band, vintage versus newly made, on-sale, ready-to-ship and the site's editorial shelves, with five sort orders. detail returns one to five listings in a single call, in full: the complete description, the condition grade and the dealer's separate condition notes, and Chairish's whole detail table, which differs by department - Number of Seats and Seat Height on a chair, Art Subject and Frame Type on a painting, Lamp Shade and Power Sources on a lamp, Primary Stone and Ring Size on a ring - published whole so nothing is lost, with period, country of origin, item type, styles, materials, colour, brand and designer promoted to named fields, plus the schema.org offer block as an independent second reading of the price. seller returns one dealer's storefront: their display name, city and state, the year they joined, the sales band the site prints, and their live inventory in the same row shape. filters returns the filter values Chairish itself serves for a scope with its own per-option counts, including the nested category tree, which is where the filter values come from. Verification on 2026-10-06 read 288 rows across five departments and twelve scopes: item id, URL, title, price, currency, price status, category path, dealer id, shipping type and ships-to countries were present on 288 of 288, every amount was in USD, no row carried a zero price, and no string in any response carried HTML or an escaped entity. Ten ids were round-tripped from search into detail: identical id, identical type, identical URL and identical price on 10 of 10. No Chairish account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
On Chairish a total can be a ceiling, a wrong filter value looks like an empty result, and a marked-down piece has two prices
Chairish stops counting at 10,000, so a category total of exactly 10,000 is a ceiling rather than a number - and two such totals cannot be compared. Its filters do not take the slugs that appear in its URLs: a style is a label, a colour is a hex code, a category is a code, and a value it does not recognise comes back as zero results rather than an error. And a discounted piece publishes both figures. This API publishes the ceiling as a flag, translates every filter into the spelling the site actually honours, refuses the one filter pair the source answers wrongly, and returns the paid price and the pre-markdown price as two separate fields.
| Request (measured 2026-10-06) | What Chairish returned | What this API does |
|---|---|---|
| A category with more than 10,000 listings | Exactly 10,000, on five unrelated categories; the same category split by item type summed to 12,793 | total_available plus total_is_capped true, so you never read the ceiling as a count |
| styles Art Deco on rings | 1,280 of 10,000+ | Returned, with the filter echoed in filters_applied |
| item_type new on rings | 5,644; vintage 7,149 | Returned |
| price_max 500 on rings | 2,566 of 10,000+ | Returned, with the band in filters_applied |
| colors FF0000 on accent chairs | 2,698 of 10,000+ | Returned |
| A style passed as a URL slug instead of a label | Zero results, HTTP 200, no error | The filters action publishes the exact labels and counts, so you never guess one |
| An unrecognised query parameter | The whole category, HTTP 200 | Never sent: only the site's own filter names reach the request |
| shipping together with styles | 2,798 - MORE rows than the style filter alone (1,280) | Refused, with both numbers, because the answer would have been wider than the filter |
| Page 100 of any category | Refused by the source; the real end of a shorter category is a clean 404 instead | page_cap 99, last_page and has_more, and page 100 is rejected with the arithmetic before any call is made |
Counts are from one minute on 2026-10-06 and move with the dealers' stock. The reachable window is 99 pages of 48 rows, that is 4,752 listings per scope, so deep inventory is reached by narrowing with a style, a colour, a price band or a sub-category. The filters action does not list values for every category - Chairish serves that list on some scopes and not others, and the response says which case you are in rather than implying the category has no filters.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/chairish/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"category": "floor-lamps",
"max_results": 12
}
}{
"ok": true,
"meta": {
"api": "chairish",
"endpoint": "search",
"mode": "live",
"latency_ms": 974.3,
"record_count": 12,
"bytes": 596088,
"cache_hit": false,
"completeness_pct": 100,
"stop_reason": "limit_reached",
"charged_credits": 1,
"version": "1.0.0",
"request_id": "df6f3836a00b4598",
"queue_ms": 1.6,
"fetched_at": "2026-10-06T14:47:17.315Z"
},
"data": {
"scope": {
"kind": "category",
"value": "floor-lamps"
},
"source_path": "/collection/floor-lamps",
"total_available": 10000,
"total_is_capped": true,
"total_cap": 10000,
"page": 1,
"page_size": 48,
"page_cap": 99,
"last_page": null,
"has_more": true,
"filters_applied": {},
"results": [
{
"item_id": "37480578",
"url": "https://www.chairish.com/product/37480578/danish-scandinavian-modern-floor-lamp-attributed-to-domus-1970s",
"title": "Danish Scandinavian Modern Floor Lamp Attributed to Domus, 1970s",
"price": 4200,
"currency": "USD",
"price_display": "$4,200",
"price_unit": null,
"price_status": "published",
"original_price": null,
"discount_percent": null,
"is_markdown": false,
"availability": "InStock",
"price_mismatch": null,
"quantity": 1,
"condition": "Refurbished",
"product_state": "Listed for Purchase",
"is_purchasable": true,
"is_on_hold": false,
"is_made_to_order": false,
"is_newly_made": false,
"lead_time": null,
"category_code": "LIGHTING:FLOOR",
"category_path": "Lighting/Lamps/Floor Lamps",
"brand": null,
"color": "Tan",
"materials": [
"Beech"
],
"dimensions_in": {
"height": 58,
"width": 17,
"depth": 29
},
"description": "Rooted in the principles of Scandinavian Modern, a 1970s Danish floor lamp in beech, attributed to Domus, with its original shade intact. The piece reflects a quiet clarity of form, where function and material are allowed to speak without excess. The structure is composed of slender beech elements, precisely joined and arranged in a vertical framework that feels both architectural and light. The wood is left largely unadorned, its grain visible beneath a soft, natural finish. This restraint is central to the design, the emphasis is not on decoration, but on proportion, balance, and the inheren",
"images": [
"https://chairish-prod.freetls.fastly.net/image/product/master/69ae088b-417f-4acc-952f-95f267a3f479/danish-scandinavian-modern-floor-lamp-attributed-to-domus-1970s-0748"
],
"seller_id": "gm4tco",
"seller_url": "https://www.chairish.com/shop/gm4tco",
"ships_from_city": "Chicago",
"ships_from_region": "LFP",
"ships_from_country": "US",
"ships_to_countries": [
"US",
"CA"
],
"shipping_type": "white-glove",
"local_pickup_available": true,
"is_promoted": false,
"badges": [
"Curator's Boost"
]
},
{
"item_id": "37009575",
"url": "https://www.chairish.com/product/37009575/selvaya-accent-floor-lamp",
"title": "Selvaya Accent Floor Lamp",
"price": 510,
"currency": "USD",
"price_display": "$510",
"price_unit": "item",
"price_status": "published",
"original_price": null,
"discount_percent": null,
"is_markdown": false,
"availability": "InStock",
"price_mismatch": null,
"quantity": 1,
"condition": "New",
"product_state": "Listed for Purchase",
"is_purchasable": true,
"is_on_hold": false,
"is_made_to_order": false,
"is_newly_made": true,
"lead_time": null,
"category_code": "LIGHTING:FLOOR",
"category_path": "Lighting/Lamps/Floor Lamps",
"brand": "Surya",
"color": "Gold",
"materials": [
"Steel"
],
"dimensions_in": {
"height": 64,
"width": 24,
"depth": 24
},
"description": "Illuminate your space with the Selvaya accent floor lamp, a perfect fusion of coastal charm and traditional elegance. Standing at 64 inches tall, this lamp is crafted from a delightful blend of felt and rattan, bringing natural texture and warmth into any room. Its coastal traditional style effortlessly complements both modern and classic decors, making it a versatile addition to your home. With its easy maintenance?simply wipe clean with a dry cloth-you'll enjoy hassle-free upkeep while avoiding harsh cleaners to preserve its stunning finish. Add the Selvaya floor lamp to your living space fo",
"images": [
"https://chairish-prod.freetls.fastly.net/image/product/master/70b7b5bc-4139-4d6e-bab9-527e2d5acc37/selvaya-accent-floor-lamp-1070"
],
"seller_id": "2zlkju",
"seller_url": "https://www.chairish.com/shop/2zlkju",
"ships_from_city": "Atlanta",
"ships_from_region": "LFP",
"ships_from_country": "US",
"ships_to_countries": [
"US"
],
"shipping_type": "D",
"local_pickup_available": false,
"is_promoted": false,
"badges": [
"Curator's Boost"
]
},
{
"item_id": "29738675",
"url": "https://www.chairish.com/product/29738675/masey-6375-floor-lamp-in-redgold",
"title": "Masey 63.75\" Off-White Cotton Shade Floor Lamp in Red/Gold",
"price": 162,
"currency": "USD",
"price_display": "$162",
"price_unit": "item",
"price_status": "published",
"original_price": null,
"discount_percent": null,
"is_markdown": false,
"availability": "InStock",
"price_mismatch": null,
"quantity": 1,
"condition": "New",
"product_state": "Listed for Purchase",
"is_purchasable": true,
"is_on_hold": false,
"is_made_to_order": false,
"is_newly_made": true,
"lead_time": null,
"category_code": "LIGHTING:FLOOR",
"category_path": "Lighting/Lamps/Floor Lamps",
"brand": "Safavieh",
"color": "Red",
"materials": [
"Iron",
"Fabric"
],
"dimensions_in": {
"height": 63.75,
"width": 18,
"depth": 18
},
"description": "Illuminate your space with style and sophistication with the MASEY 63.75 inch red and gold metal floor lamp. This striking lamp features a bold red metal body complemented by elegant gold accents, creating a visual allure that is both modern and timeless. The design beautifully balances the sleek lines of metal with the soft, ambient glow from its fabric shade. Transform any room into a space of warmth and character with this unique floor lamp. Its commanding height and vibrant colors make it a stunning focal point in living rooms, bedrooms, or offices. The MASEY floor lamp is not just about l",
"images": [
"https://chairish-prod.freetls.fastly.net/image/product/master/1a5d3bb4-494f-4578-bb62-b33f6b063b04/masey-6375-off-white-cotton-shade-floor-lamp-in-redgold-0971"
],
"seller_id": "0awib9",
"seller_url": "https://www.chairish.com/shop/0awib9",
"ships_from_city": "Philadelphia",
"ships_from_region": "LFP",
"ships_from_country": "US",
"ships_to_countries": [
"US"
],
"shipping_type": "standard-parcel",
"local_pickup_available": false,
"is_promoted": false,
"badges": []
}
]
}
}What the Chairish API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search or browse Chairish's live US marketplace of vintage, antique and used design. Scope the request with free text, a collection path, a brand/designer storefront or one of the site's own keyword pages, then narrow it with the site's own facets: style label, category code, colour hex, price band, vintage vs newly made, on-sale, ready-to-ship, editorial shelf. Every row carries the price AND the pre-markdown price when the seller has discounted it, the currency, the dealer id with their city and state, the condition, the brand, the colour, the materials and the height/width/depth in inches — the measurements are the question buyers actually ask in this market. Exactly one upstream page per call; the source serves 48 rows per page. Exactly one of `query`, `category`, `maker` or `keyword` is required: the source serves one scope at a time and combining two returns nothing. The source's own count comes back as `total_available`, with `total_is_capped: true` when it has hit the site's 10,000 ceiling — two capped totals are not comparable and this endpoint says so rather than pretending otherwise. | Pricing teams call search to search or browse Chairish's live US marketplace of vintage, antique and used design. | query, category, maker, keyword, styles, ... |
| detail | The full listing page for one to five items: the dealer's complete description, every photo, the price with its pre-markdown figure, the condition grade AND the dealer's own condition notes, and the site's whole detail table. That table is per vertical — a chair publishes Number of Seats and Seat Height, a painting publishes Art Subject and Framing, a lamp publishes Lamp Shade — so it is returned whole in `details[]` and projected into `attributes{}`, with period, country of origin, item type, styles, materials, colour, brand and designer promoted to named fields. Includes the dealer's shop handle, display name, city/state, year they joined and the sales band the site prints, plus the schema.org offer block as an independent second witness on the price and the availability. | Marketplace operators call detail to get the full listing page for one to five items. | item |
| seller | One dealer's storefront: who they are (display name, city and state, the year they joined Chairish, the sales band the site prints) and their live inventory with the same row shape as `search`, filterable the same way. Takes the vanity slug from a /shop/<slug> URL or the dealer id a search row returns as `seller_id`. A dealer who exists but currently lists nothing is an answer, not an error: `has_live_inventory` is false and `results` is empty. An unknown handle is NOT_FOUND. | Catalog enrichment teams call seller to get one dealer's storefront. | seller, styles, categories, colors, item_type, ... |
| filters | The filter values Chairish itself serves for a scope, with its own counts: the category tree (code, label, count, nested up to three deep), style labels, colour hex codes, price bands, availability, sales, shipping options and the vertical-specific facets (Number of Seats, Art Subject, Art Size, Art Orientation, Lamp Shade). Use it to learn the exact values `search` accepts instead of guessing — a value the source does not know returns an honest zero rather than an error, so guessing is expensive. 🔴 The site does not serve this list for every scope: measured within one minute, /collection/rings served 17 facets and /collection/seating served none. When that happens `filters_available` is false and `filters` is empty — the endpoint reports the gap instead of implying the scope has no filters. A dealer storefront (`seller`) has served them on every sample. Takes the same scope pair as `search`, or a `seller` handle. | Retail analysts call filters to get the filter values Chairish itself serves for a scope, with its own counts. | query, category, maker, keyword, seller |
Call search from your stack
curl -X POST https://api.reefapi.com/chairish/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"category":"floor-lamps","max_results":12}'import requests
r = requests.post(
"https://api.reefapi.com/chairish/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"category": "floor-lamps",
"max_results": 12
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/chairish/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"category": "floor-lamps",
"max_results": 12
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.chairish.search with {"category":"floor-lamps","max_results":12}.Who uses this API and why
- Price research on a specific designer, brand or style - pull the live USD price, the pre-markdown price and the discount on every Herman Miller, Art Deco or Mid-Century Modern listing, and track how a segment is actually clearing.
- Sourcing for a dealer or interior designer - filter a category by style, colour, price band and vintage-versus-new, then read the exact height, width and depth in inches to see what fits a room before anyone picks up a phone.
- Competitive monitoring for a vintage marketplace or an auction house - watch a category's on-sale share, markdown depth and newly-listed flow, and follow named dealers through their storefronts.
- Enriching a resale or valuation model - every listing carries period, country of origin, materials, condition grade, the dealer's own condition notes and the full description, which is the feature set a condition-and-provenance model needs.
- Building a decor or furniture discovery product - search, filter and listing detail with photos, dimensions and dealer location, from one key, without maintaining a scraper against a marketplace that changes its grid.
Questions developers ask before integrating
What does Chairish actually sell, and what does the API cover?
Vintage, antique and used design, plus a newly-made tail from the same dealers: seating, tables, casegoods and storage, beds, lighting of every kind, rugs in every standard size, fine art including paintings, prints, photography and sculpture, mirrors and wall accents, decor and objects, tableware and barware, textiles and pillows, outdoor furniture, and jewellery including rings, necklaces, earrings and watches. You scope a search by the collection path Chairish uses in its own URL - floor-lamps, accent-chairs, rings, rugs/persian, paintings/abstract - or by a brand or designer storefront, or by free text, or by one of the site's keyword pages. The filters action returns the nested category tree with live counts, so you never have to guess a path.
What currency are the prices in, and what happens with a discounted piece?
Chairish is a US marketplace and lists in US dollars: currency was USD on 288 of 288 rows read on 2026-10-06. The amount and the currency code are always read as a pair out of the row's own data, so a figure can never be relabelled. When a dealer has marked a piece down you get three fields: price is what a buyer pays, original_price is the pre-markdown figure, and discount_percent is the percentage Chairish itself prints - not one we recompute. 68 of those 288 rows were markdowns.
Can a price ever come back as zero?
No. price_status is one of published, sold, not_purchasable or not_published, and price is null for the last of those - never 0, and never a guess. Across 288 rows, 285 were published and 3 were not_purchasable, which on Chairish means a lot listed at auction rather than for immediate purchase: it has an amount, but you cannot buy at it, and that is a different thing from sold. Zero prices: 0 of 288.
How complete are the dimensions?
Height, width and depth come back as numbers in inches, exactly as Chairish publishes them, with no conversion applied. Measured fill on 24 rows per category: 24 of 24 on accent chairs, floor lamps, Persian rugs, paintings, coffee tables, a brand storefront and a keyword page. The honest exception is jewellery - Chairish ring listings carry no dimension table, so the figures came back on 3 of 24 and are null on the rest rather than invented. The detail action additionally returns the site's own display string, for example 22.5ʺW × 23.75ʺD × 41ʺH, and a chair also carries Seat Height and Number of Seats as separate rows.
How much does one listing return?
The dealer's full description, every photo, the price pair, the condition grade and the dealer's separate condition notes, and Chairish's entire detail table. That table is different in every department, so it is returned whole in details and projected into attributes rather than squeezed into a fixed shape: a chair carries Number of Seats and Seat Height, a lamp carries Lamp Shade and Power Sources, a rug carries Rug Construction and Pattern, a painting carries Art Subject and Frame Type, a ring carries Primary Stone, Primary Stone Shape, Primary Stone Creation and Ring Size. Period, country of origin, item type, styles, materials, colour, brand and designer are promoted to named fields because they mean the same thing in every department. Measured on 10 listings across five departments: description, condition notes, period, item type, styles, materials, colour, the detail table and the dealer block came back on 10 of 10.
What do you get about the dealer?
Every search row carries the dealer id and a direct link to their storefront, plus the city, state and country the piece ships from. The seller action resolves a storefront by its handle or by that same dealer id and returns the dealer's display name, their town and state, the year they joined Chairish and the sales band the site prints - for example 10+ sales, 250+ sales, 2.5k+ sales - together with their live inventory in the same row shape as search, filterable the same way. Verified on 7 dealers: 7 of 7 resolved with name, location, year and band. A dealer who exists but currently lists nothing comes back with has_live_inventory false rather than as an error; an unknown handle is NOT_FOUND.
Does it return shipping costs?
No, and it does not pretend to. Chairish computes a shipping quote from the buyer's own postal code, which is not something this API sends, so instead of a fabricated number you get what the listing itself publishes: shipping_type - white-glove, standard-parcel, freight, local-pickup-only or arranged-by-seller - the list of countries the piece ships to, whether free local pickup is offered, and the dealer's own city and state so you can judge distance yourself. Those were present on 288 of 288 rows.
What does Chairish not publish, that this API therefore does not return?
Four things, all of them null rather than guessed. There is no trade or private-sale price, because those sit behind a signed-in buyer. There is no sold price and no sold archive, because sold listings leave the public browse surface. There is no exact dealer sales count - Chairish prints a band and that band is what you get. And there are no reviews or ratings on a listing. The reachable window also stops at 4,752 listings per scope, which is the source's limit, not a choice; narrowing the search is how you get past it.
What is the Chairish API?
Chairish API is a ReefAPI endpoint group for us marketplace for vintage and used design: furniture, lighting, rugs, art, decor and jewellery with usd prices, period, materials, dimensions in inches, condition and the dealer. It returns live JSON through POST requests under /chairish/v1.
Is the Chairish API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Chairish calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Chairish login or account?
No login to Chairish 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 Chairish 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 Chairish API use?
Chairish actions currently cost 3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Chairish from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call chairish actions with the same key, credit pool and JSON envelope used by normal REST requests.