search_products
[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 (" ")
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Optional size filter (e.g. "10.5", "M", "UK 8"). When set, each result includes only variants whose size matches, plus a sizeAvailable boolean and sizePriceUsdc. Results with sizeAvailable=false are still returned (marked unavailable) so the agent can report correctly. | |
| limit | No | Max results (default 10) | |
| query | Yes | Free-text query. Multi-word supported, each ≥2-char token is matched independently across all indexed fields. | |
| brand_slug | No | Optional brand slug to scope the search. Call list_brands to see slugs. |