{"openapi":"3.0.3","info":{"title":"GrailPeople API","description":"Creator beauty intelligence API. Turns YouTube creator videos into structured, creator-attributed product recommendations with timestamped quotes. Data is built from video transcripts, product mention extraction, canonical normalization, web enrichment, and creator metadata. All public endpoints apply a quality gate: needsReview=false OR (needsReview=true AND confidence>=90). Endorsement strength uses a 6-label system: holy grail / loves it / worth trying / mentions / mixed / not recommended.","version":"1.0.0","contact":{"url":"https://grailpeople.com"}},"servers":[{"url":"https://grailpeople.com","description":"Production"}],"paths":{"/api/v1/products":{"get":{"summary":"List enriched products","description":"Returns canonical products enriched with brand, product name, shade, type, finish, price, retailers, and ingredients. All products have been extracted from creator videos and enriched via web search.","operationId":"listProducts","parameters":[{"name":"q","in":"query","description":"Free-text search across brand, product name, and shade.","schema":{"type":"string"},"example":"blush"},{"name":"brand","in":"query","description":"Case-insensitive brand filter.","schema":{"type":"string"},"example":"Charlotte Tilbury"},{"name":"category","in":"query","description":"Product category.","schema":{"type":"string","enum":["FACE","LIP","EYES","SKINCARE","BATH_BODY","HAIR","TOOLS","OTHER"]}},{"name":"subcategory","in":"query","description":"Product subcategory (e.g. blush, foundation, mascara, serum).","schema":{"type":"string"},"example":"blush"},{"name":"formulation","in":"query","description":"Product formulation (e.g. powder, liquid, cream, stick).","schema":{"type":"string"},"example":"cream"},{"name":"price_tier","in":"query","description":"Brand price tier.","schema":{"type":"string","enum":["drugstore","mid_range","luxury"]}},{"name":"finish","in":"query","description":"Product finish.","schema":{"type":"string"},"example":"matte"},{"name":"retailer","in":"query","description":"Exact retailer name contained in enriched retailers.","schema":{"type":"string"},"example":"Sephora"},{"name":"limit","in":"query","description":"Max products to return. Default 50, max 200.","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","description":"Pagination offset. Default 0.","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}}}}},"/api/v1/products/{slug}":{"get":{"summary":"Get product evidence dossier","description":"Returns the full creator evidence dossier for one product. Merges all shade variants that share the same slug into a single response. Use this to answer 'Is [product] worth it?' — returns every creator who mentioned it, their exact quotes with timestamps, endorsement strengths, signal counts, caveats, and where to buy. This is the highest-value AI endpoint.","operationId":"getProductEvidence","parameters":[{"name":"slug","in":"path","required":true,"description":"Product slug shared across shade variants (e.g. 'aestura-atobarrier365-cream', 'beauty-of-joseon-relief-sun'). Returned as product_slug in /recommendations.","schema":{"type":"string"},"example":"aestura-atobarrier365-cream"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ProductEvidence"}}}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Product not found"}}}}}}}}},"/api/v1/recommendations":{"get":{"summary":"Get product recommendations","description":"Returns product recommendations grouped by canonical product and ranked by a rating-weighted score that sums each creator's numeric endorsement_rating (1–5) centered on 3.5, so strong endorsements add, mixed/not-recommended subtract, and neutral mentions are zero; ties break on mention count. Applies quality gate to all mentions. Includes creator quotes, signal counts, consensus summaries, caveats, price, and retailers. Use endorsed_only=true for 'what should I buy?' queries. Use concern= for skin concerns like acne or redness (best-effort text match). Use max_price_usd= for budget queries. Creator-verified evidence-tag filters: verified= and origin= are HARD (narrow the set, honest empty result if nothing qualifies); skin_tone/skin_type/look/attribute/routine_context/preference/value are SOFT (re-rank, never exclude). See the Evidence Tags section in /llms.txt for the full signal model.","operationId":"getRecommendations","parameters":[{"name":"q","in":"query","description":"Free-text search across brand, product name, and shade.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Product category.","schema":{"type":"string","enum":["FACE","LIP","EYES","SKINCARE","BATH_BODY","HAIR","TOOLS","OTHER"]}},{"name":"subcategory","in":"query","description":"Product subcategory (e.g. spf, moisturizer, foundation, serum).","schema":{"type":"string"},"example":"spf"},{"name":"formulation","in":"query","description":"Product formulation.","schema":{"type":"string"},"example":"cream"},{"name":"price_tier","in":"query","description":"Brand price tier.","schema":{"type":"string","enum":["drugstore","mid_range","luxury"]}},{"name":"finish","in":"query","description":"Product finish.","schema":{"type":"string"},"example":"dewy"},{"name":"retailer","in":"query","description":"Exact retailer name in enriched retailers.","schema":{"type":"string"}},{"name":"creator","in":"query","description":"Filter to one creator's recommendations by handle.","schema":{"type":"string"},"example":"drugstoremaven"},{"name":"ingredient","in":"query","description":"Filter by key ingredient (case-insensitive, partial match). Examples: hyaluronic acid, niacinamide, retinol, ceramide, azelaic acid.","schema":{"type":"string"},"example":"niacinamide"},{"name":"concern","in":"query","description":"Beauty concern — matches against product claims, creator quote topics, and consensus summary. Use underscores for multi-word values (e.g. oily_skin, dark_circles). Hyphens and spaces also accepted. Skincare: acne, hormonal_acne, cystic_acne, blackheads, whiteheads, texture, large_pores, oily_skin, dry_skin, dehydrated_skin, sensitive_skin, rosacea, eczema, post_acne_marks, melasma, uneven_skin_tone, dull_skin, fine_lines, wrinkles, dark_circles, puffy_eyes, damaged_skin_barrier. Makeup: foundation_shade_match, makeup_longevity, cakey_makeup, patchy_makeup, mascara_for_lashes, lip_dryness. Hair (beta): frizzy_hair, dry_damaged_hair, oily_scalp, hair_thinning, dandruff. Any unrecognized value falls back to a raw text match against product summaries.","schema":{"type":"string"},"example":"oily_skin"},{"name":"max_price_usd","in":"query","description":"Maximum price in USD (best-effort — coverage is partial; some products have no price data).","schema":{"type":"number"},"example":40},{"name":"creator_type","in":"query","description":"Filter or prefer creators by specialty. Examples: dermatologist, makeup artist, esthetician.","schema":{"type":"string"},"example":"dermatologist"},{"name":"endorsed_only","in":"query","description":"If true, only return products with holy grail, loves it, or worth trying endorsements — the three positive levels (excludes neutral mentions, mixed, and not recommended).","schema":{"type":"boolean"}},{"name":"verified","in":"query","description":"HARD filter on creator-verified claim tags. Returns only products carrying ALL listed claims (comma = AND). Stronger than brand marketing claims — these are extracted from creator quotes. An unrecognized value returns an honest empty result (data:[] with meta.missing/meta.unverified), never the unfiltered catalog.","schema":{"type":"string","enum":["no_white_cast","non_comedogenic","fragrance_free","vegan","cruelty_free","fungal_acne_safe","pregnancy_safe","alcohol_free","oil_free","sulfate_free"]},"example":"no_white_cast,fragrance_free"},{"name":"origin","in":"query","description":"HARD filter on brand home-culture (brand_origin_tags). An unrecognized value returns an honest empty result, never the unfiltered catalog.","schema":{"type":"string","enum":["k_beauty","j_beauty","c_beauty","southeast_asian_beauty","indian_beauty","french_pharmacy","us_beauty"]},"example":"k_beauty"},{"name":"skin_tone","in":"query","description":"SOFT rank boost — shade-match depth the product suits (distinct from skin_type). Answers 'foundation for olive/brown skin'. Re-ranks, never excludes.","schema":{"type":"string","enum":["fair","olive","tan","brown","deep"]},"example":"brown"},{"name":"skin_type","in":"query","description":"SOFT rank boost — skin type the product suits. Re-ranks, never excludes.","schema":{"type":"string","enum":["oily","dry","combination","sensitive","mature","all_skin_types"]},"example":"oily"},{"name":"look","in":"query","description":"SOFT rank boost — makeup look. Re-ranks, never excludes.","schema":{"type":"string","enum":["natural_everyday","no_makeup_makeup","dewy_glow","soft_glam","full_glam","smokey_eye","bold_lip"]},"example":"natural_everyday"},{"name":"attribute","in":"query","description":"SOFT rank boost — texture / wear / performance trait (e.g. lightweight, long_wearing, hydrating, full_coverage, glass_skin, oil_controlling, non_greasy, buildable). Re-ranks, never excludes.","schema":{"type":"string"},"example":"long_wearing"},{"name":"routine_context","in":"query","description":"SOFT rank boost — when/where used. Re-ranks, never excludes.","schema":{"type":"string","enum":["am","pm","daytime","nighttime","everyday","summer","winter","spring","fall","travel","under_makeup"]},"example":"summer"},{"name":"preference","in":"query","description":"SOFT rank boost — buyer preference. Re-ranks, never excludes.","schema":{"type":"string","enum":["simple_minimal","beginner_friendly","multitasking","clean_beauty"]},"example":"beginner_friendly"},{"name":"value","in":"query","description":"SOFT rank boost — value perception. Re-ranks, never excludes.","schema":{"type":"string","enum":["value_for_money"]},"example":"value_for_money"},{"name":"limit","in":"query","description":"Max recommendations to return. Default 20, max 100.","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}}}}}}}}},"/api/v1/creators":{"get":{"summary":"List creators","description":"Returns all indexed beauty creators with platform metadata and product mention counts, ordered by product count descending.","operationId":"listCreators","parameters":[{"name":"platform","in":"query","description":"Filter by platform.","schema":{"type":"string","enum":["youtube","tiktok"]}},{"name":"min_products","in":"query","description":"Minimum number of products mentioned. Default 1.","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Creator"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}}}}},"/api/v1/creators/{handle}":{"get":{"summary":"Get creator product history","description":"Returns one creator's full product history with quality-gated mentions, structured quotes with timestamps, endorsement strengths, specialty, and years active. Use endorsed_only=true to show only the creator's strongest picks. Use subcategory= to narrow by product type. Use category= to filter by top-level category (e.g. HAIR for all hair products).","operationId":"getCreator","parameters":[{"name":"handle","in":"path","required":true,"description":"Creator handle (lowercase, no @).","schema":{"type":"string"},"example":"drdrayzday"},{"name":"endorsed_only","in":"query","description":"If true, only return products with holy grail, loves it, or worth trying endorsements (the three positive levels).","schema":{"type":"boolean"}},{"name":"subcategory","in":"query","description":"Narrow to a product type (e.g. spf, moisturizer, serum).","schema":{"type":"string"},"example":"spf"},{"name":"category","in":"query","description":"Filter by product category.","schema":{"type":"string","enum":["FACE","LIP","EYES","SKINCARE","BATH_BODY","HAIR","TOOLS","OTHER"]},"example":"HAIR"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/CreatorDetail"}}}}}},"404":{"description":"Creator not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Creator not found"}}}}}}}}},"/api/v1/brands":{"get":{"summary":"List brands","description":"Returns all brands with at least one indexed, enriched product. Includes AI-generated verdict where available.","operationId":"listBrands","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}}}}},"/api/v1/brands/{slug}":{"get":{"summary":"Get brand detail","description":"Returns full brand detail: AI-generated verdict, signature products, creator list, and all products grouped by canonical product. Includes caveats when any product has mixed or negative evidence.","operationId":"getBrand","parameters":[{"name":"slug","in":"path","required":true,"description":"Brand slug: lowercase, spaces → hyphens (e.g. 'charlotte-tilbury', 'beauty-of-joseon', 'skin1004').","schema":{"type":"string"},"example":"aestura"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/BrandDetail"}}}}}},"404":{"description":"Brand not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Brand not found"}}}}}}}}}},"components":{"schemas":{"Product":{"type":"object","description":"One enriched canonical product from /api/v1/products. Field names match the route response.","properties":{"id":{"type":"string","format":"uuid"},"canonicalBrand":{"type":"string","nullable":true,"example":"Charlotte Tilbury"},"canonicalProductName":{"type":"string","nullable":true,"example":"Pillow Talk Lipstick"},"canonicalShade":{"type":"string","nullable":true,"example":"Pillow Talk"},"productType":{"type":"string","nullable":true,"example":"lipstick"},"subcategory":{"type":"string","nullable":true,"example":"lipstick"},"formulation":{"type":"string","nullable":true,"example":"cream"},"finish":{"type":"string","nullable":true,"example":"satin"},"priceTier":{"type":"string","nullable":true,"enum":["drugstore","mid_range","luxury"]},"pigmentLevel":{"type":"string","nullable":true},"enrichedPrice":{"type":"string","nullable":true,"example":"$34"},"priceAmount":{"type":"number","nullable":true,"example":34,"description":"Best-effort numeric parse from enrichedPrice."},"enrichedRetailers":{"type":"array","items":{"type":"string"},"example":["Sephora","Nordstrom"]},"updatedAt":{"type":"string","format":"date-time","nullable":true},"keyIngredients":{"type":"array","items":{"type":"string"}},"productSlug":{"type":"string","nullable":true,"example":"charlotte-tilbury-pillow-talk-lipstick","description":"Shared across shade variants. Use with /api/v1/products/{slug}."},"consensusSummary":{"type":"string","nullable":true},"consensusSummaryGeneratedAt":{"type":"string","format":"date-time","nullable":true},"consensusSummaryQuoteCount":{"type":"integer","nullable":true},"consensusSummaryModel":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"creators":{"type":"array","description":"Distinct quality-gated creators for this product list row.","items":{"type":"object","properties":{"handle":{"type":"string","nullable":true},"endorsementStrength":{"type":"string","nullable":true,"enum":["holy grail","loves it","worth trying","mentions","mixed","not recommended"]},"videoUrl":{"type":"string","nullable":true}}}},"mention_count":{"type":"integer"}}},"Recommendation":{"type":"object","description":"A canonical product with creator evidence, signal counts, and consensus data. Ranked by endorsement-weighted score.","properties":{"id":{"type":"string","format":"uuid","description":"Canonical product ID."},"brand":{"type":"string","nullable":true,"example":"Beauty of Joseon"},"name":{"type":"string","nullable":true,"example":"Relief Sun: Rice + Probiotics"},"shade":{"type":"string","nullable":true},"product_type":{"type":"string","nullable":true,"example":"sunscreen","description":"Raw product type label from extraction (e.g. 'sunscreen', 'moisturizer', 'serum')."},"subcategory":{"type":"string","nullable":true,"example":"spf"},"formulation":{"type":"string","nullable":true},"finish":{"type":"string","nullable":true},"price_tier":{"type":"string","nullable":true,"enum":["drugstore","mid_range","luxury"]},"enriched_price":{"type":"string","nullable":true,"example":"$12–$18"},"enriched_price_usd":{"type":"number","nullable":true,"example":15},"enriched_retailers":{"type":"array","items":{"type":"string"},"example":["YesStyle","Amazon"]},"key_ingredients":{"type":"array","items":{"type":"string"}},"product_slug":{"type":"string","nullable":true,"example":"beauty-of-joseon-relief-sun"},"product_url":{"type":"string","nullable":true,"example":"/products/beauty-of-joseon-relief-sun"},"consensus_summary":{"type":"string","nullable":true,"description":"AI-generated 2-3 sentence verdict from creator quotes."},"signal":{"type":"object","description":"Endorsement signal counts across all quality-gated mentions for this product.","properties":{"total_mentions":{"type":"integer"},"holy_grail_count":{"type":"integer"},"loves_it_count":{"type":"integer"},"worth_trying_count":{"type":"integer"},"mentions_count":{"type":"integer"},"mixed_count":{"type":"integer"},"not_recommended_count":{"type":"integer"},"unsponsored_count":{"type":"integer"},"sponsored_count":{"type":"integer"}}},"caveats":{"type":"object","nullable":true,"description":"Honest evidence limitations. Present when evidence is mixed, sparse, or incomplete.","properties":{"mixed_evidence":{"type":"boolean"},"single_creator":{"type":"boolean"},"no_price_data":{"type":"boolean"},"has_negative":{"type":"boolean"},"mixed_note":{"type":"string","nullable":true},"negative_note":{"type":"string","nullable":true}}},"creators":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"specialty":{"type":"array","items":{"type":"string"},"description":"e.g. ['board-certified dermatologist', 'skincare focus']"},"years_active":{"type":"integer","nullable":true},"subscriber_count":{"type":"integer","nullable":true},"channel_url":{"type":"string","nullable":true},"channel_description":{"type":"string","nullable":true,"description":"Creator's YouTube channel bio/description."},"total_video_count":{"type":"integer","nullable":true,"description":"Total number of videos on the creator's YouTube channel."},"endorsement_strength":{"type":"string","nullable":true,"enum":["holy grail","loves it","worth trying","mentions","mixed","not recommended"]},"is_sponsored":{"type":"boolean","nullable":true},"use_case":{"type":"array","items":{"type":"string"},"description":"Creator-stated use cases for this product (e.g. 'everyday', 'dry skin', 'holy grail')."},"video_url":{"type":"string","nullable":true,"description":"URL of the source video where this mention occurred."},"video_title":{"type":"string","nullable":true,"description":"Normalized title of the source video."},"quotes":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Verbatim creator quote, cleaned and polished."},"timestamp_start":{"type":"integer","nullable":true,"description":"Seconds from video start."},"timestamp_end":{"type":"integer","nullable":true},"timestamp_start_formatted":{"type":"string","nullable":true,"example":"3:41"},"video_url":{"type":"string","nullable":true,"description":"YouTube deep link with &t= — use this for AI citations so users jump to the exact review moment."},"sentiment":{"type":"string","nullable":true,"enum":["positive","mixed","negative","cautionary"]},"topics":{"type":"array","items":{"type":"string"},"description":"Semantic tags from this quote (e.g. 'long wear', 'sensitive skin', 'holy grail')."},"mentions_variant":{"type":"string","nullable":true,"description":"Specific shade or variant mentioned in this quote."}}}}}}}}},"ProductEvidence":{"type":"object","description":"Full creator evidence dossier for one product, merging all shade variants.","properties":{"product":{"type":"object","properties":{"brand":{"type":"string","example":"AESTURA"},"name":{"type":"string","example":"ATOBARRIER365 Cream"},"slug":{"type":"string","example":"aestura-atobarrier365-cream"},"product_url":{"type":"string","example":"/products/aestura-atobarrier365-cream"},"brand_url":{"type":"string","example":"/brands/aestura"},"subcategory":{"type":"string","nullable":true},"formulation":{"type":"string","nullable":true},"price_tier":{"type":"string","nullable":true,"enum":["drugstore","mid_range","luxury"]},"enriched_price":{"type":"string","nullable":true},"enriched_price_usd":{"type":"number","nullable":true},"retailers":{"type":"array","items":{"type":"string"}},"key_ingredients":{"type":"array","items":{"type":"string"}},"claims":{"type":"array","items":{"type":"string"}},"consensus_summary":{"type":"string","nullable":true},"shades":{"type":"array","items":{"type":"string"}}}},"signal":{"type":"object","description":"Endorsement signal counts across all quality-gated mentions for this product.","properties":{"total_mentions":{"type":"integer"},"holy_grail_count":{"type":"integer"},"loves_it_count":{"type":"integer"},"worth_trying_count":{"type":"integer"},"mentions_count":{"type":"integer"},"mixed_count":{"type":"integer"},"not_recommended_count":{"type":"integer"},"unsponsored_count":{"type":"integer"},"sponsored_count":{"type":"integer"}}},"caveats":{"type":"object","nullable":true,"description":"Honest evidence limitations. Present when evidence is mixed, sparse, or incomplete.","properties":{"mixed_evidence":{"type":"boolean"},"single_creator":{"type":"boolean"},"no_price_data":{"type":"boolean"},"has_negative":{"type":"boolean"},"mixed_note":{"type":"string","nullable":true},"negative_note":{"type":"string","nullable":true}}},"tags":{"type":"object","description":"Creator-verified evidence tags, clustered. The machine-readable signals to compare products on. Nine groups (claim, attribute, concern, skin_type, skin_tone, look, routine_context, preference, value) sorted into these six clusters. Thresholds: claim + skin_tone show at >=1 supporting mention, other positive groups at >=2, negatives at >=1; the count is always shown.","properties":{"claims":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Creator-verified product claims (fragrance_free, no_white_cast, fungal_acne_safe, etc.). Stronger than brand marketing claims."},"attributes":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Texture / wear / performance traits."},"good_for":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Skin type, skin tone, and concern matches."},"best_for":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Look and routine-context fit."},"value":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}}},"warnings":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Negative-polarity tags with inverted phrasing (e.g. 'leaves a white cast')."}}},"limitations":{"type":"array","items":{"type":"string"},"description":"Honest data gaps for this product (e.g. single-creator evidence, no price data)."},"creators":{"type":"array","description":"Sorted strongest endorsement first.","items":{"type":"object","properties":{"handle":{"type":"string"},"display_name":{"type":"string","nullable":true},"profile_url":{"type":"string","example":"/creators/hyram"},"channel_url":{"type":"string","nullable":true},"specialty":{"type":"array","items":{"type":"string"}},"years_active":{"type":"integer","nullable":true},"subscriber_count":{"type":"integer","nullable":true},"endorsement_strength":{"type":"string","enum":["holy grail","loves it","worth trying","mentions","mixed","not recommended"]},"is_sponsored":{"type":"boolean"},"video_titles":{"type":"array","items":{"type":"string"},"description":"Deduplicated titles of all source videos this creator mentioned the product in."},"quotes":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Verbatim creator quote, cleaned and polished."},"timestamp_start":{"type":"integer","nullable":true,"description":"Seconds from video start."},"timestamp_end":{"type":"integer","nullable":true},"timestamp_start_formatted":{"type":"string","nullable":true,"example":"3:41"},"video_url":{"type":"string","nullable":true,"description":"YouTube deep link with &t= — use this for AI citations so users jump to the exact review moment."},"sentiment":{"type":"string","nullable":true,"enum":["positive","mixed","negative","cautionary"]},"topics":{"type":"array","items":{"type":"string"},"description":"Semantic tags from this quote (e.g. 'long wear', 'sensitive skin', 'holy grail')."},"mentions_variant":{"type":"string","nullable":true,"description":"Specific shade or variant mentioned in this quote."}}}}}}}}},"Creator":{"type":"object","properties":{"handle":{"type":"string","example":"drdrayzday"},"display_name":{"type":"string","nullable":true,"example":"Dr. Dray"},"platform":{"type":"string","nullable":true,"example":"youtube"},"subscriber_count":{"type":"integer","nullable":true},"channel_url":{"type":"string","nullable":true},"product_count":{"type":"integer"}}},"CreatorDetail":{"type":"object","properties":{"handle":{"type":"string"},"display_name":{"type":"string","nullable":true},"platform":{"type":"string","nullable":true},"subscriber_count":{"type":"integer","nullable":true},"channel_url":{"type":"string","nullable":true},"channel_description":{"type":"string","nullable":true},"profile_url":{"type":"string","example":"/creators/drdrayzday"},"specialty":{"type":"array","items":{"type":"string"},"description":"Creator specialty labels (e.g. ['board-certified dermatologist', 'skincare focus'])."},"years_active":{"type":"integer","nullable":true,"description":"Derived from channel_created_at."},"product_count":{"type":"integer"},"category_breakdown":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count of products per category (e.g. { SKINCARE: 40, FACE: 12 }).","example":{"SKINCARE":40,"FACE":12}},"products":{"type":"array","description":"Deduplicated by product slug. Each entry represents one unique product (collapsing multiple mention rows for the same product across different videos).","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"brand":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"shade":{"type":"string","nullable":true},"subcategory":{"type":"string","nullable":true},"product_type":{"type":"string","nullable":true},"finish":{"type":"string","nullable":true},"enriched_price":{"type":"string","nullable":true},"enriched_retailers":{"type":"array","items":{"type":"string"}},"product_slug":{"type":"string","nullable":true},"product_url":{"type":"string","nullable":true},"category":{"type":"string","nullable":true,"enum":["FACE","LIP","EYES","SKINCARE","BATH_BODY","HAIR","TOOLS","OTHER"]},"mention_count":{"type":"integer","description":"How many of this creator's videos mentioned this product."},"endorsement_strength":{"type":"string","nullable":true,"enum":["holy grail","loves it","worth trying","mentions","mixed","not recommended"]},"is_sponsored":{"type":"boolean","description":"True if any quality-gated mention in this creator/product group was sponsored."},"video_url":{"type":"string","nullable":true,"description":"URL of the first (highest-confidence) source video."},"video_title":{"type":"string","nullable":true,"description":"Title of the first (highest-confidence) source video."},"quotes":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Verbatim creator quote, cleaned and polished."},"timestamp_start":{"type":"integer","nullable":true,"description":"Seconds from video start."},"timestamp_end":{"type":"integer","nullable":true},"timestamp_start_formatted":{"type":"string","nullable":true,"example":"3:41"},"video_url":{"type":"string","nullable":true,"description":"YouTube deep link with &t= — use this for AI citations so users jump to the exact review moment."},"sentiment":{"type":"string","nullable":true,"enum":["positive","mixed","negative","cautionary"]},"topics":{"type":"array","items":{"type":"string"},"description":"Semantic tags from this quote (e.g. 'long wear', 'sensitive skin', 'holy grail')."},"mentions_variant":{"type":"string","nullable":true,"description":"Specific shade or variant mentioned in this quote."}}}}}}},"tags":{"type":"object","description":"Creator-verified evidence tags, clustered. The machine-readable signals to compare products on. Nine groups (claim, attribute, concern, skin_type, skin_tone, look, routine_context, preference, value) sorted into these six clusters. Thresholds: claim + skin_tone show at >=1 supporting mention, other positive groups at >=2, negatives at >=1; the count is always shown.","properties":{"claims":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Creator-verified product claims (fragrance_free, no_white_cast, fungal_acne_safe, etc.). Stronger than brand marketing claims."},"attributes":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Texture / wear / performance traits."},"good_for":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Skin type, skin tone, and concern matches."},"best_for":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Look and routine-context fit."},"value":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}}},"warnings":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Negative-polarity tags with inverted phrasing (e.g. 'leaves a white cast')."}}}}},"Brand":{"type":"object","properties":{"brand":{"type":"string","example":"Charlotte Tilbury"},"slug":{"type":"string","example":"charlotte-tilbury","description":"Use with /api/v1/brands/{slug}."},"price_tier":{"type":"string","nullable":true,"enum":["drugstore","mid_range","luxury"]},"product_count":{"type":"integer","example":12},"creator_count":{"type":"integer","example":5},"retailer_list":{"type":"array","items":{"type":"string"},"example":["Sephora","Nordstrom"]},"top_subcategories":{"type":"array","items":{"type":"string"}},"verdict":{"type":"string","nullable":true,"description":"AI-generated creator consensus verdict."},"summary_generated_at":{"type":"string","format":"date-time","nullable":true},"url":{"type":"string","example":"/brands/charlotte-tilbury"}}},"BrandDetail":{"type":"object","properties":{"brand":{"type":"string"},"slug":{"type":"string"},"price_tier":{"type":"string","nullable":true,"enum":["drugstore","mid_range","luxury"]},"origin":{"type":"string","nullable":true,"enum":["k_beauty","j_beauty","c_beauty","southeast_asian_beauty","indian_beauty","french_pharmacy","us_beauty"],"description":"Brand home-culture (brand_origin_tags). Null if unmapped."},"origin_label":{"type":"string","nullable":true,"description":"Human-readable origin (e.g. 'K-beauty')."},"product_count":{"type":"integer"},"creator_count":{"type":"integer"},"tags":{"type":"object","description":"Brand-level evidence tags aggregated across the lineup (counts = distinct products).","properties":{"claims":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Creator-verified product claims (fragrance_free, no_white_cast, fungal_acne_safe, etc.). Stronger than brand marketing claims."},"attributes":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Texture / wear / performance traits."},"good_for":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Skin type, skin tone, and concern matches."},"best_for":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Look and routine-context fit."},"value":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}}},"warnings":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","example":"no_white_cast","description":"Canonical tag slug."},"label":{"type":"string","example":"No white cast","description":"Human-readable label."},"group":{"type":"string","enum":["claim","attribute","concern","skin_type","skin_tone","look","routine_context","preference","value"]},"polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"negative = a warning (surfaced in the warnings cluster with inverted phrasing)."},"mention_count":{"type":"integer","description":"Distinct supporting creator mentions (product/creator surfaces)."},"product_count":{"type":"integer","description":"Distinct supporting products (brand surfaces)."},"source_type":{"type":"string","enum":["creator_quote","llm_tagger","video_title","deepseek"],"description":"Provenance: creator_quote (creator said it, highest trust), llm_tagger (LLM read the creator's quote text — same trust tier as creator_quote), video_title (implied by the video title, neutral context), deepseek (legacy LLM batch, pre-tagger)."},"sample_quote":{"type":"string","nullable":true,"description":"A representative supporting quote or title snippet."},"warning_text":{"type":"string","description":"Present only on negative tags — the inverted human-readable warning."},"provenance":{"type":"array","description":"Links each tag back to the creator, channel (sameAs), and source video.","items":{"type":"object","properties":{"creator_handle":{"type":"string","nullable":true},"creator_name":{"type":"string","nullable":true},"channel_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}}}}},"description":"Negative-polarity tags with inverted phrasing (e.g. 'leaves a white cast')."}}},"top_subcategories":{"type":"array","items":{"type":"string"}},"retailer_list":{"type":"array","items":{"type":"string"}},"creator_list":{"type":"array","items":{"type":"string"},"description":"All creator handles who reviewed this brand's products."},"signature_products":{"type":"array","description":"Top 5 products by creator mention count.","items":{"type":"object","properties":{"name":{"type":"string"},"product_slug":{"type":"string"},"url":{"type":"string"},"creator_count":{"type":"integer"}}}},"summary":{"type":"object","nullable":true,"description":"AI-generated brand summary. Null if not yet generated.","properties":{"verdict":{"type":"string","nullable":true},"generated_at":{"type":"string","format":"date-time","nullable":true},"quote_count":{"type":"integer","nullable":true},"model":{"type":"string","nullable":true},"prompt_version":{"type":"integer","nullable":true}}},"caveats":{"type":"object","nullable":true,"description":"Present when any product in this brand has mixed or negative evidence.","properties":{"mixed_evidence":{"type":"boolean"},"single_creator":{"type":"boolean"},"no_price_data":{"type":"boolean"},"has_negative":{"type":"boolean"},"mixed_note":{"type":"string","nullable":true},"negative_note":{"type":"string","nullable":true}}},"products":{"type":"array","items":{"type":"object","properties":{"product_slug":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"shades":{"type":"array","items":{"type":"string"}},"subcategory":{"type":"string","nullable":true},"formulation":{"type":"string","nullable":true},"price_tier":{"type":"string","nullable":true,"enum":["drugstore","mid_range","luxury"]},"enriched_price":{"type":"string","nullable":true},"enriched_price_usd":{"type":"number","nullable":true},"retailers":{"type":"array","items":{"type":"string"}},"creator_count":{"type":"integer"},"has_strong_endorsement":{"type":"boolean","description":"True if any creator endorsed a product from this brand (holy grail, loves it, or worth trying — the same endorsed=yes definition used by endorsed_only)."},"has_mixed_evidence":{"type":"boolean"},"consensus_summary":{"type":"string","nullable":true},"top_quotes":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Verbatim creator quote, cleaned and polished."},"timestamp_start":{"type":"integer","nullable":true,"description":"Seconds from video start."},"timestamp_end":{"type":"integer","nullable":true},"timestamp_start_formatted":{"type":"string","nullable":true,"example":"3:41"},"video_url":{"type":"string","nullable":true,"description":"YouTube deep link with &t= — use this for AI citations so users jump to the exact review moment."},"sentiment":{"type":"string","nullable":true,"enum":["positive","mixed","negative","cautionary"]},"topics":{"type":"array","items":{"type":"string"},"description":"Semantic tags from this quote (e.g. 'long wear', 'sensitive skin', 'holy grail')."},"mentions_variant":{"type":"string","nullable":true,"description":"Specific shade or variant mentioned in this quote."}}}}}}}}}}}}