TheRealReal

Keyword search across the live catalogue with every filter the site exposes (category, designer, condition grade, colour, size, gender, store, price range, on-sale, vintage, with-tags, editors' picks) and its own sorts. Each row carries the asking price, the original retail estimate where the source publishes one, the condition grade, sold flag and images. Some brand/model terms ('birkin', 'kelly bag') are answered by the site with a curated collection instead of results — this action follows that redirect and says so in `followed_redirect`.

Browse a category, a designer, a curated sale or any filter combination without a keyword — the catalogue view. Same row shape and sorts as `search`. At least one of category, category_id, designer, designer_id, sale_slug or a facet filter is required, so nobody accidentally pages through four million rows.

One listing in full, by slug or URL: name, designer, category path, the CONDITION GRADE plus the condition narrative the site writes, the seller description as clean lines, measurements with the unit as published, materials and colours, asking price with the markdown against the site's own previous price, the ORIGINAL RETAIL ESTIMATE where the source publishes one, sold state, return policy, disclaimers and every image with its dimensions. A sold listing resolves normally — it is a state, not an error.

Up to 50 listings in ONE upstream call, by slug — the shape a catalogue refresh or a price/availability watcher should use instead of 50 separate detail calls. Slugs that no longer resolve come back in `not_found` rather than failing the call.

Visually similar LIVE listings for one product id — the answer to 'this one-of-a-kind item is sold, what else is like it'. Same row shape as search.

SOLD comparables: what items matching a description actually sold for on TheRealReal, with the transacted price, the consignor commission percentage the site quotes on that price and the resulting payout, plus the condition grade of each comp. This is the resale pricing surface — the live catalogue only shows asking prices.

The search box's own autocomplete for a partial term — the cheapest way to find the phrasing the catalogue actually indexes.

TheRealReal's own demand signal, as three ranked lists of designer + item-class pairs: what is selling fastest, what is most wishlisted and what is searched most. This is the site's own read on its market, not a metric this API computes.

The designer index for one department — 5 417 names for women, 2 745 for men — each with the facet id `browse` takes. Use `search`/`browse` with `designer` (slug) or `designer_id`.

The live category tree with a live item count per node — the `category` permalinks every other action takes. Optionally scoped to one department or designer.

Every facet the catalogue exposes for a given scope, with live counts and the exact ids the filter params take: condition grades, colours, clothing and shoe sizes, gender, designers, physical stores, the price range and the boolean flags. Call this instead of hard-coding an id.