{"openapi":"3.0.3","info":{"title":"Grailed API (ReefAPI)","version":"1.0.0","description":"Grailed API scraper — curated menswear, streetwear & archive-fashion resale data from grailed.com: search listings with price/size/designer/category/condition filters, full listing detail (description, measurements, photos, seller), SOLD comps for price history, designer & seller storefront listings — no API key required Call POST /grailed/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/grailed-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Grailed API documentation","url":"https://reefapi.com/docs/grailed"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"grailed","description":"Grailed API scraper — curated menswear, streetwear & archive-fashion resale data from grailed.com: search listings with price/size/designer/category/condition filters, full listing detail (description, measurements, photos, seller), SOLD comps for price history, designer & seller storefront listings — no API key required"}],"paths":{"/grailed/v1/search":{"post":{"operationId":"grailed_search","summary":"Search Grailed listings by keyword + filters (designer, category, size, color, condition, department, strata, location, price band) with sorting and pagination","description":"Search Grailed listings by keyword + filters (designer, category, size, color, condition, department, strata, location, price band) with sorting and pagination. Returns live listings with price, size, condition, designer, photos and a seller summary. The catalog-discovery surface.","tags":["grailed"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"stone island jacket","description":"Keywords to search for (give query and/or at least one filter — empty query + a filter browses that facet)."},"designer":{"type":"string","example":"Stone Island","description":"Filter to one designer/brand by its EXACT Grailed name (e.g. 'Stone Island', 'Rick Owens', 'Supreme'). Resolve the exact name with the `designers` action."},"category":{"type":"string","enum":["tops","bottoms","outerwear","footwear","tailoring","accessories","womens_tops","womens_bottoms","womens_outerwear","womens_dresses","womens_footwear","womens_accessories","womens_bags_luggage","womens_jewelry"],"description":"Top-level category facet."},"category_path":{"type":"string","example":"outerwear.denim_jackets","description":"Advanced: exact sub-category path (e.g. 'outerwear.denim_jackets', 'footwear.hi_top_sneakers'). Copy from a listing's category_path."},"department":{"type":"string","enum":["menswear","womenswear"],"description":"Menswear or womenswear section."},"size":{"type":"string","example":"m","description":"Size facet (e.g. 'm', 's', 'us 10', '32'). Sizes are category specific — copy the exact value from a search result's `size`."},"color":{"type":"string","enum":["black","white","gray","brown","beige","blue","green","red","purple","pink","yellow","orange","silver","gold","multi"],"description":"Primary color facet."},"condition":{"type":"string","enum":["is_new","is_gently_used","is_used","is_worn","is_not_specified"],"description":"Item condition."},"strata":{"type":"string","enum":["grailed","hype","sartorial","basic"],"description":"Grailed market tier (curation level)."},"location":{"type":"string","enum":["United States","Canada","United Kingdom","Europe","Asia","Australia/NZ","Other"],"description":"Seller location region."},"price_from":{"type":"number","minimum":0,"example":100,"description":"Only listings at or above this price (USD)."},"price_to":{"type":"number","minimum":0,"example":500,"description":"Only listings at or below this price (USD)."},"sort":{"type":"string","enum":["relevance","newest","price_low","price_high","most_popular","recently_bumped"],"default":"relevance","description":"Result ordering."},"page":{"type":"integer","minimum":1,"maximum":200,"default":1,"description":"Page number (Algolia serves up to 200 pages per query)."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":40,"description":"Results per page (1–100)."}}},"example":{"query":"stone island","per_page":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/grailed/v1/listing_detail":{"post":{"operationId":"grailed_listing_detail","summary":"Full detail for one listing by `id` or `url`: title, description, price, size (pretty + exact), condition, color, category, all photos, measurements, traits, shipping table, designers, sold price, and","description":"Full detail for one listing by `id` or `url`: title, description, price, size (pretty + exact), condition, color, category, all photos, measurements, traits, shipping table, designers, sold price, and a seller summary.","tags":["grailed"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"99122353","description":"Grailed listing id — the digits in the listing URL (grailed.com/listings/<id>-slug). Take it from search results. Provide id OR url."},"url":{"type":"string","example":"https://www.grailed.com/listings/99122353","description":"Full Grailed listing URL — alternative to id."}}},"example":{"id":"99122353"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/grailed/v1/sold_listings":{"post":{"operationId":"grailed_sold_listings","summary":"Search SOLD listings (resale comps) by keyword + the same filters as search","description":"Search SOLD listings (resale comps) by keyword + the same filters as search. Each result carries its sold_price and sold_at — the price-history / market-value moat for valuing menswear, streetwear and archive pieces.","tags":["grailed"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"supreme box logo","description":"Keywords for the sold-comps search (give query and/or a filter)."},"designer":{"type":"string","example":"Stone Island","description":"Filter to one designer/brand by its EXACT Grailed name (e.g. 'Stone Island', 'Rick Owens', 'Supreme'). Resolve the exact name with the `designers` action."},"category":{"type":"string","enum":["tops","bottoms","outerwear","footwear","tailoring","accessories","womens_tops","womens_bottoms","womens_outerwear","womens_dresses","womens_footwear","womens_accessories","womens_bags_luggage","womens_jewelry"],"description":"Top-level category facet."},"department":{"type":"string","enum":["menswear","womenswear"],"description":"Menswear or womenswear section."},"size":{"type":"string","example":"m","description":"Size facet (e.g. 'm', 's', 'us 10', '32'). Sizes are category specific — copy the exact value from a search result's `size`."},"color":{"type":"string","enum":["black","white","gray","brown","beige","blue","green","red","purple","pink","yellow","orange","silver","gold","multi"],"description":"Primary color facet."},"condition":{"type":"string","enum":["is_new","is_gently_used","is_used","is_worn","is_not_specified"],"description":"Item condition."},"strata":{"type":"string","enum":["grailed","hype","sartorial","basic"],"description":"Grailed market tier (curation level)."},"price_from":{"type":"number","minimum":0,"example":100,"description":"Only listings at or above this price (USD)."},"price_to":{"type":"number","minimum":0,"example":500,"description":"Only listings at or below this price (USD)."},"sort":{"type":"string","enum":["newest","relevance","price_high","price_low"],"default":"newest","description":"Sold-comp ordering."},"page":{"type":"integer","minimum":1,"maximum":200,"default":1,"description":"Page number (Algolia serves up to 200 pages per query)."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":40,"description":"Results per page (1–100)."}}},"example":{"query":"supreme","per_page":5}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/grailed/v1/seller_listings":{"post":{"operationId":"grailed_seller_listings","summary":"All active listings from one seller's storefront by `seller_id`","description":"All active listings from one seller's storefront by `seller_id`. Same listing shape as search; paginated. Resolve a seller_id from any search/detail result's seller.id.","tags":["grailed"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seller_id":{"type":"string","example":"1335538","description":"Grailed seller (user) id — take it from a listing's seller.id."},"query":{"type":"string","description":"Optional keyword to search within this seller's items."},"category":{"type":"string","enum":["tops","bottoms","outerwear","footwear","tailoring","accessories","womens_tops","womens_bottoms","womens_outerwear","womens_dresses","womens_footwear","womens_accessories","womens_bags_luggage","womens_jewelry"],"description":"Top-level category facet."},"designer":{"type":"string","example":"Stone Island","description":"Filter to one designer/brand by its EXACT Grailed name (e.g. 'Stone Island', 'Rick Owens', 'Supreme'). Resolve the exact name with the `designers` action."},"sort":{"type":"string","enum":["relevance","newest","price_low","price_high","most_popular","recently_bumped"],"default":"relevance","description":"Result ordering."},"page":{"type":"integer","minimum":1,"maximum":200,"default":1,"description":"Page number (Algolia serves up to 200 pages per query)."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":40,"description":"Results per page (1–100)."}},"required":["seller_id"]},"example":{"seller_id":"1335538"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/grailed/v1/designers":{"post":{"operationId":"grailed_designers","summary":"Search Grailed's designer/brand directory by name → id, slug, listings_count, logo and departments","description":"Search Grailed's designer/brand directory by name → id, slug, listings_count, logo and departments. Use the returned exact `name` to filter search/sold_listings by designer, and the `slug` for the `designer_detail` action.","tags":["grailed"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"stone","description":"Designer/brand name (or part of it) to look up."},"page":{"type":"integer","minimum":1,"maximum":200,"default":1,"description":"Page number (Algolia serves up to 200 pages per query)."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":40,"description":"Results per page (1–100)."}},"required":["query"]},"example":{"query":"stone"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/grailed/v1/designer_detail":{"post":{"operationId":"grailed_designer_detail","summary":"Designer/brand profile by `slug`: id, title, description, follower count and the exact name to use as a designer filter.","description":"Designer/brand profile by `slug`: id, title, description, follower count and the exact name to use as a designer filter.","tags":["grailed"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","example":"stone-island","description":"Designer slug from a designer URL (grailed.com/designers/<slug>) or the `designers` action."}},"required":["slug"]},"example":{"slug":"stone-island"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}