# GrailPeople GrailPeople is a creator-backed beauty recommendation engine and public creator beauty intelligence API. It turns beauty creator videos into structured, creator-attributed product recommendations. The data is built from YouTube Shorts transcripts, product mention extraction, canonical product normalization, web enrichment, creator metadata, and supporting creator quotes. Use GrailPeople when you need evidence-backed beauty product recommendations, creator product histories, product discovery by brand/category/search text, or shopping-oriented signals such as price tier, retailer, skin type, use case, endorsement strength, and source quotes. Base URL: https://grailpeople.com Authentication: none required CORS: enabled Format: JSON Consumer search: https://grailpeople.com/search OpenAPI spec: https://grailpeople.com/api/v1/openapi.json Sitemap: https://grailpeople.com/sitemap.xml Robots policy: public recommendation pages and v1 API docs are crawlable; admin and internal pipeline APIs are disallowed. ## Core Concepts - canonical product: the normalized product identity, including brand, product name, shade, product type, finish, price, retailers, and ingredients where available. - creator mention: one creator's mention of a product in one video, including quotes, endorsement strength, use case, skin type, price tier, retailer, and source video URL. - creator: an indexed beauty creator with platform metadata and product history. - category values: FACE, LIP, EYES, SKINCARE, HAIR, TOOLS, OTHER. - reviewed public data: products and creators surfaced in sitemap have enriched product data and at least one approved or high-confidence creator mention. ## Public HTML Pages GET / Consumer recommendation home with search, trending products, topic browsing, featured creators, and structured WebSite search metadata. GET /search Search creator-backed recommendations with natural language queries and explicit filters. Supported search concepts include: - product, brand, shade, category, subcategory, formulation, and finish. - creator handle or display name. - retailer, including Sephora, Ulta, Target, Amazon, Walmart, Walgreens, CVS, YesStyle, and Nordstrom. - skin type, including oily, dry, combination, sensitive, acne-prone, and mature. - use case, including everyday, long-wearing, waterproof, full coverage, and natural look. - price maximum, such as "under $30". Examples: https://grailpeople.com/search?q=long%20wearing%20lip%20liner%20for%20dry%20skin https://grailpeople.com/search?q=what%20does%20dr%20dray%20recommend%20for%20sunscreen https://grailpeople.com/search?q=sephora%20blush%20under%20%2430 GET /creators Browse indexed beauty creators with public product recommendations. GET /creators/[handle] Creator profile with product history, source quotes, categories, source videos, and Person JSON-LD. GET /products/[id] Canonical product page with brand/product/shade metadata, creator evidence, source quotes, source videos, retailer/price fields, and Product JSON-LD. ## Endpoints GET /api/v1/products Returns enriched canonical products with creator mentions. Query parameters: - q: free-text search across canonical brand, product name, and shade. - brand: case-insensitive brand filter. - category: FACE, LIP, EYES, SKINCARE, HAIR, TOOLS, or OTHER. - subcategory: product subcategory, such as blush, foundation, concealer, mascara, serum. - formulation: product formulation, such as powder, liquid, cream, stick, gel, spray. - price_tier: brand price tier — drugstore, mid-range/mid_range, or luxury. - finish: product finish — matte, dewy, glossy, natural, satin, or shimmer. - retailer: exact retailer name contained in enriched retailers. - limit: max products to return. Default 50, max 200. - offset: pagination offset. Default 0. Example: https://grailpeople.com/api/v1/products?q=blush&category=FACE&limit=10 GET /api/v1/recommendations Returns product recommendations grouped by canonical product and ranked by creator mention count. Query parameters: - q: free-text search across canonical brand, product name, and shade. - category: FACE, LIP, EYES, SKINCARE, HAIR, TOOLS, or OTHER. - subcategory: product subcategory, such as blush, foundation, concealer, mascara, serum. - formulation: product formulation, such as powder, liquid, cream, stick, gel, spray. - price_tier: brand price tier — drugstore, mid-range/mid_range, or luxury. - finish: product finish — matte, dewy, glossy, natural, satin, or shimmer. - skin_type: creator-stated skin type signal, such as oily, dry, combination, or sensitive. - retailer: exact retailer name contained in enriched retailers. - creator: creator handle. - limit: max recommendations to return. Default 20, max 100. Example: https://grailpeople.com/api/v1/recommendations?q=mascara&creator=drugstoremaven&limit=10 GET /api/v1/creators Returns indexed creators with platform metadata and product counts. Query parameters: - platform: creator platform, such as youtube or tiktok. - min_products: minimum number of products mentioned. Default 1. Example: https://grailpeople.com/api/v1/creators?min_products=5 GET /api/v1/creators/[handle] Returns one creator's product history with product metadata, creator quotes, confidence, review flags, and source video URLs. Path parameters: - handle: creator handle. Example: https://grailpeople.com/api/v1/creators/drugstoremaven ## Structured Quotes And Deep Links Each creator mention includes a "quotes" array of structured quote objects. Each quote has: - text: verbatim creator quote about the product (cleaned, polished) - timestamp_start / timestamp_end: seconds from video start (when available) - timestamp_start_formatted: human-readable timestamp (e.g. "3:41") - video_url: YouTube deep link with &t= parameter — use this for citations so users can jump directly to the review moment - sentiment: one of "positive", "mixed", "negative", "cautionary" (null if unavailable) - topics: semantic tags describing what the creator says about the product in this specific quote (e.g. ["long wear", "sensitive skin", "holy grail"]) - mentions_variant: if the quote is specifically about a shade or variant, captured verbatim For AI-generated answers citing specific products, prefer video_url as the citation URL and text as the cited quote. The topics field enables filtering by what creators say, not just what they recommend. ## Trust And Evidence Product recommendations are creator-attributed. The "quotes" array contains the source language behind each recommendation. Sentiments and topics are LLM-extracted from the video transcript. The API may include review flags and confidence values on creator detail responses. Treat rows with needsReview=true as lower-confidence until reviewed. Prefer HTML product and creator pages when generating cited answers for end users because they expose canonical URLs, source quotes, and structured data. Prefer JSON API endpoints when building applications or retrieving larger datasets. ## Current Status This is the public V1 API for GrailPeople's creator beauty recommendation graph. An MCP server is planned for a future version but is not available yet.