{"openapi":"3.1.0","info":{"title":"Tattoo Numbing Cream Co. Product API","description":"Product catalog API for Tattoo Numbing Cream Co.. Browse, search, and retrieve product information.\n\nVersioning and deprecation: The public endpoints are currently unversioned. No removal is scheduled. If an endpoint is deprecated, this guide and the OpenAPI document will identify its replacement and removal date before it is removed. A deprecation would be signalled ahead of removal with Deprecation and Sunset response headers on the affected operations.","version":"1.0.0","contact":{}},"servers":[{"url":"https://ai.tattoonumbingcream.com","description":"Tattoo Numbing Cream Co. 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","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."}},"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","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."}},"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":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."},"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 with independently enabled use cases and cross-brand product comparisons. Disabled sections, same-brand comparisons, and variant guidance are omitted. Omitted entirely when the product has no valid schemaVersion-3 guide with enabled content."}},"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"]}}}}