[FIND] START HERE when you know what you want. Free-text search across every active RRG listing.
This endpoint answers DEFINED intent, not open browse. Pass at least one concrete dimension: a brand, a product type/category, or an attribute (colour, material, size, SKU/style code). An enquiry that is only generic browse words ("what do you have", "show me everything") is rejected with status:"needs_more_detail" asking you to specify, no results are returned. To browse without intent, call list_drops instead.
Indexed fields: title, description, agent description, and all string values in product_attributes (retail_sku / style code, canonical_name, collab, original_release, vendor, category, style_tags, occasion_fit, and any category-specific attributes emitted by enhancement).
Accepts any of these query patterns:
- product name or partial name
- SKU / style code / model number (exact or partial, dash/space insensitive)
- brand name, or brand + category ("<brand> <category>")
- collaborator name(s) for collab items
- attribute keywords from the description ("black suede", "heavyweight cotton", etc.)
Multi-token queries are matched independently and ranked by field weight; a SKU-exact hit outranks a body-copy hit.
Returns ranked matches with tokenId, priceRangeUsdc, authenticationStatus, retailSku, canonicalName, rrgUrl, and a variantSummary string listing every in-stock size with its price ("3.5=$1583, 4=$1899, 10.5=$770, …").
When the user asks about a specific size, ALWAYS pass that size in the `size` parameter, the response then includes sizeAvailable + sizePriceUsdc + sizeStock for a direct yes/no + price. For queries like "size 10.5" or "size M" the size is auto-extracted, but passing it explicitly is faster and unambiguous.
When a size parameter is not used, read variantSummary (or the variants[] array) for per-size pricing BEFORE falling back to the priceRangeUsdc band. Per-size prices are exact; the band is only a floor→ceiling range.
Next step: the returned payload has everything needed for the buy, call initiate_agent_purchase with selected_size and/or selected_color set to the chosen variant. Pass selected_color whenever the listing has a colour axis (variants[].color non-null) so fulfillment ships the right finish. get_drop_details is optional (adds signed image URLs + shipping context).
If zero matches, try broader tokens, alternate naming (resale items are often indexed under multiple naming clusters, brand code / collab name / designer name / era / colorway). If still zero, call list_drops to browse.
