{"openapi":"3.1.0","info":{"title":"ClearRetain Product API","description":"Product catalog API for ClearRetain. Browse, search, and retrieve product information.","version":"1.0.0","contact":{}},"servers":[{"url":"https://ai.clearretain.com","description":"ClearRetain storefront"}],"paths":{"/products.json":{"get":{"operationId":"listProducts","summary":"List products","description":"Retrieve a paginated list of products with optional filtering by category, brand, availability, and text search.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Text search across product titles and descriptions"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by product category"},{"name":"brand","in":"query","schema":{"type":"string"},"description":"Filter by brand name"},{"name":"availability","in":"query","schema":{"type":"string","enum":["in_stock","out_of_stock","preorder","backorder"]},"description":"Filter by availability status"},{"name":"sort","in":"query","schema":{"type":"string","enum":["title_asc","price_asc","price_desc","rating","newest","relevance"]},"description":"Sort order for results"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Maximum number of products to return"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of products to skip for pagination"}],"responses":{"200":{"description":"A paginated list of products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["products","pagination"]}}}},"404":{"description":"Store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{itemId}.json":{"get":{"operationId":"getProduct","summary":"Get product details","description":"Retrieve full details for a single product including variants, shipping, reviews, and return policy.","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"The product catalog ID"}],"responses":{"200":{"description":"Product details","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/ProductDetail"}},"required":["product"]}}}},"404":{"description":"Product or store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/redirect":{"get":{"operationId":"redirectToProduct","summary":"Redirect to merchant product page","description":"Redirect the user to the original merchant product page. Provide either a product_id or a search query to match a product.","parameters":[{"name":"product_id","in":"query","schema":{"type":"string"},"description":"The product catalog ID to redirect to"},{"name":"query","in":"query","schema":{"type":"string"},"description":"Search query to find and redirect to the best matching product"}],"responses":{"302":{"description":"Redirect to the merchant product page","headers":{"Location":{"schema":{"type":"string","format":"uri"},"description":"The merchant product URL"}}},"400":{"description":"Missing product_id or query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brand-facts.json":{"get":{"operationId":"getBrandFacts","summary":"Get brand facts","description":"Retrieve structured brand information including store policies, support details, and product metadata. Supports conditional requests via If-Modified-Since.","parameters":[{"name":"If-Modified-Since","in":"header","schema":{"type":"string","format":"date-time"},"description":"Return 304 Not Modified if the brand facts have not changed since this date"}],"responses":{"200":{"description":"Brand facts object","content":{"application/json":{"schema":{"type":"object","description":"Structured brand information. Shape varies per store configuration."}}},"headers":{"Last-Modified":{"schema":{"type":"string"},"description":"When the brand facts were last updated"}}},"304":{"description":"Brand facts have not been modified since the requested date"},"404":{"description":"Store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Product":{"type":"object","properties":{"catalog_id":{"type":"string"},"item_id":{"type":["string","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"image_url":{"type":["string","null"],"format":"uri"},"additional_image_urls":{"type":["array","null"],"items":{"type":"string","format":"uri"}},"brand":{"type":["string","null"]},"price":{"type":["string","null"],"description":"Formatted price string, e.g. \"29.99 USD\""},"sale_price":{"type":["string","null"]},"availability":{"type":["string","null"],"enum":["in_stock","out_of_stock","preorder","backorder",null]},"product_category":{"type":["string","null"]},"star_rating":{"type":["number","null"],"minimum":0,"maximum":5},"review_count":{"type":["integer","null"],"minimum":0},"condition":{"type":["string","null"],"enum":["new","refurbished","used",null]},"product_insights":{"type":"array","description":"LLM-facing sections only; merchant-review claims and the source artifact summary are not included.","items":{"$ref":"#/components/schemas/ProductInsightSection"}},"product_guide":{"$ref":"#/components/schemas/ProductGuide","description":"Optional buying guide: use cases, documented variant guidance and one compact product comparison with a cited summary per product. Omitted when the product has no valid schemaVersion-3 guide."}},"required":["catalog_id"]},"ProductDetail":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"group_id":{"type":["string","null"]},"has_variants":{"type":"boolean"},"variants":{"type":"object","properties":{"color":{"type":["string","null"]},"size":{"type":["string","null"]},"custom":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"option":{"type":"string"}},"required":["category","option"]}}}},"gender":{"type":["string","null"],"enum":["male","female","unisex",null]},"gtin":{"type":["string","null"]},"mpn":{"type":["string","null"]},"inventory_quantity":{"type":["integer","null"]},"shipping":{"description":"Shipping configuration object"},"delivery_estimate":{"type":["string","null"]},"return_policy":{"type":["string","null"]},"return_window_days":{"type":["integer","null"]},"accepts_returns":{"type":"boolean"},"reviews":{"description":"Product reviews data"},"target_countries":{"type":["string","null"]},"popularity_score":{"type":["number","null"]},"updated_at":{"type":"string","format":"date-time"}}}]},"ProductInsightProvenance":{"type":"object","description":"Source families and resolved URLs that ground one product-insight item.","properties":{"productData":{"type":"boolean"},"reviews":{"type":"boolean"},"qna":{"type":"boolean"},"urls":{"type":"array","items":{"type":"string","format":"uri"}}},"required":["productData","reviews","qna","urls"]},"ProductInsightItem":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"group":{"type":"string"},"detail":{"type":"string"},"claimType":{"type":"string"},"sourceTier":{"type":"string","enum":["primary","secondary"]},"provenance":{"$ref":"#/components/schemas/ProductInsightProvenance"}},"required":["value","provenance"]},"ProductInsightSection":{"type":"object","description":"An LLM-facing Product Insights section whose items carry compact provenance.","properties":{"title":{"type":"string"},"type":{"type":"string","enum":["key_value","card","bullets","paragraph","faq","comparison"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductInsightItem"}}},"required":["title","type","items"]},"ProductGuideSource":{"type":"object","description":"A cited source of the decision guide. Every sourceIds value in the guide resolves to one of these entries.","properties":{"id":{"type":"string"},"label":{"type":"string"},"url":{"type":"string","format":"uri"},"domain":{"type":"string"},"productRef":{"type":"string"},"sourceType":{"type":"string","enum":["focal_brand_pdp","alternative_brand_pdp","retailer_pdp","marketplace_pdp","unknown_pdp"],"description":"Where this product-page evidence came from."}},"required":["id","label","url","domain"]},"ProductGuideUseCase":{"type":"object","description":"One buyer situation the product is a good fit for, or not.","properties":{"id":{"type":"string"},"label":{"type":"string"},"audience":{"type":"string"},"buyerJob":{"type":"string"},"constraint":{"type":"string"},"outcome":{"type":"string"},"recommendation":{"type":"string"},"alternative":{"type":"object","description":"The product to choose instead (notBestFor entries).","properties":{"type":{"type":"string"},"refId":{"type":"string","description":"A comparison subject refId"},"label":{"type":"string"}},"required":["type","label"]},"claimAddress":{"type":"string"},"sourceIds":{"type":"array","items":{"type":"string"}}},"required":["id","label","recommendation","sourceIds"]},"ProductGuideDecisionRule":{"type":"object","description":"When to choose the option identified by chooseRefId.","properties":{"id":{"type":"string"},"chooseRefId":{"type":"string"},"when":{"type":"string"},"because":{"type":"string"},"claimAddress":{"type":"string"},"sourceIds":{"type":"array","items":{"type":"string"}}},"required":["id","chooseRefId","when","sourceIds"]},"ProductGuideDecisionValue":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["key","label","value"]},"ProductGuideVariantChoice":{"type":"object","properties":{"refId":{"type":"string"},"targetType":{"type":"string"},"variantId":{"type":"string"},"label":{"type":"string"},"price":{"type":"string"},"availability":{"type":"string"},"isCurrentSelection":{"type":"boolean","description":"True for the merchant listing's default variant. The storefront page shows every variant side by side and does not mark one as selected."},"decisionValues":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideDecisionValue"}},"sourceIds":{"type":"array","items":{"type":"string"}}},"required":["refId","targetType","label","isCurrentSelection","decisionValues","sourceIds"]},"ProductGuideVariantComparison":{"type":"object","description":"Choosing between variants of this product along one axis.","properties":{"id":{"type":"string"},"comparisonType":{"type":"string","enum":["variant_selection"]},"title":{"type":"string"},"focalProductRef":{"type":"string"},"axis":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"merchantOptionName":{"type":"string"}},"required":["key","label"]},"choices":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ProductGuideVariantChoice"}},"decisionRules":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideDecisionRule"}}},"required":["id","comparisonType","title","choices","decisionRules"]},"ProductGuideSubject":{"type":"object","description":"One product in the compact product comparison.","properties":{"refId":{"type":"string"},"targetType":{"type":"string","const":"product"},"title":{"type":"string"},"brand":{"type":"string"},"url":{"type":"string","format":"uri"},"price":{"type":"string"},"availability":{"type":"string"},"isFocal":{"type":"boolean","description":"True for the product this JSON describes."},"relationship":{"type":"string","enum":["focal","same_brand","cross_brand"]}},"required":["refId","targetType","title","isFocal"]},"ProductGuideProductSummary":{"type":"object","description":"One cited summary explaining why and when to choose a product.","properties":{"productRef":{"type":"string"},"summary":{"type":"string"},"sourceIds":{"type":"array","minItems":1,"items":{"type":"string"}}},"required":["productRef","summary","sourceIds"]},"ProductGuideProductComparison":{"type":"object","description":"One compact comparison with one cited summary for every displayed product.","properties":{"id":{"type":"string"},"comparisonType":{"type":"string","const":"product_comparison"},"title":{"type":"string"},"focalProductRef":{"type":"string"},"subjects":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ProductGuideSubject"}},"summaries":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ProductGuideProductSummary"}}},"required":["id","comparisonType","title","focalProductRef","subjects","summaries"]},"ProductGuide":{"type":"object","description":"Evidence-backed buying guide (contract schemaVersion 3). Read useCases for fit, variantSelection for documented option differences and productComparison for one cited summary per product. Every sourceIds value resolves in sources.","properties":{"id":{"type":"string"},"schemaVersion":{"type":"integer","const":3},"title":{"type":"string"},"answer":{"type":"string","deprecated":true,"description":"Deprecated compatibility field; the storefront does not display it."},"useCases":{"type":"object","properties":{"bestFor":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideUseCase"}},"notBestFor":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideUseCase"}}},"required":["bestFor","notBestFor"]},"comparisons":{"type":"object","properties":{"variantSelection":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideVariantComparison"}},"productComparison":{"$ref":"#/components/schemas/ProductGuideProductComparison"}},"required":["variantSelection"]},"sources":{"type":"array","description":"Only the sources the guide cites.","items":{"$ref":"#/components/schemas/ProductGuideSource"}}},"required":["id","schemaVersion","title","useCases","comparisons","sources"]},"Pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["total","limit","offset","has_more"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}