# Social Fetch API - Sephora endpoints # Base URL: https://api.socialfetch.dev # Auth: x-api-key header (sfk_...) # Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json # Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json 12 documented Sephora operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported. ## GET /v1/sephora/product Get Sephora product Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/product/get.mdx SDK: client.sephora.getProduct({ productId: "P442563" }) Parameters: - productId (required, string) - Sephora product id (`P442563`) or product page URL (`https://www.sephora.com/product/aha-30-bha-2-peeling-solution-P442563`). - skuId (optional, string) - Shade or size to select (`2210607`); `selectedSkuId` echoes it. Default: the one the product page opens on. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/product?productId=P442563" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/product/reviews List Sephora product reviews Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/product/reviews/get.mdx SDK: client.sephora.getProductReviews({ productId: "P442563", limit: 30 }) Parameters: - productId (required, string) - Sephora product id (`P442563`) or product page URL (`https://www.sephora.com/product/aha-30-bha-2-peeling-solution-P442563`). - sort (optional, string, enum: newest | oldest | highest_rating | lowest_rating | most_helpful) - Order of the reviews: `newest` (default), `oldest`, `highest_rating`, `lowest_rating` or `most_helpful`. - rating (optional, integer) - Only reviews with this many stars, 1 to 5. Default: every rating. - limit (optional, integer) - Reviews per page, 1 to 100. Default: 30. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. It only works with the same filters. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/product/reviews?productId=P442563" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/product/questions List Sephora product questions Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/product/questions/get.mdx SDK: client.sephora.getProductQuestions({ productId: "P442563" }) Parameters: - productId (required, string) - Sephora product id (`P442563`) or product page URL (`https://www.sephora.com/product/aha-30-bha-2-peeling-solution-P442563`). - sort (optional, string, enum: newest | oldest | most_answered | recently_answered) - Order of the questions: `newest` (default), `oldest`, `most_answered` or `recently_answered`. - limit (optional, integer) - Questions per page, 1 to 100. Default: 20. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. It only works with the same filters. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/product/questions?productId=P442563" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/search Search Sephora products Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/search/get.mdx SDK: client.sephora.search({ query: "vitamin c serum" }) Parameters: - query (required, string) - Words to search for, up to 100 characters (`vitamin c serum`). - sort (optional, string, enum: relevance | bestselling | top_rated | newest | price_high_to_low | price_low_to_high) - Order of the products: `relevance` (default), `bestselling`, `top_rated`, `newest`, `price_high_to_low` or `price_low_to_high`. - limit (optional, integer) - Products per page, 1 to 60. Default: 60. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. It only works with the same filters. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/search?query=vitamin%20c%20serum" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/search/suggestions List Sephora search suggestions Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/search/suggestions/get.mdx SDK: client.sephora.getSearchSuggestions({ query: "lip" }) Parameters: - query (required, string) - What the shopper has typed so far, up to 100 characters (`lip`). Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/search/suggestions?query=lip" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/categories List Sephora categories Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/categories/get.mdx SDK: client.sephora.listCategories({ depth: 1 }) Parameters: - depth (optional, integer) - Levels of subcategories to include under each top-level category, 0 to 3. Default: 0. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/categories?depth=1" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/category Get Sephora category Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/category/get.mdx SDK: client.sephora.getCategory({ category: "cat150006" }) Parameters: - category (required, string) - Category id (`cat150006`), category page URL (`https://www.sephora.com/shop/skincare`) or its slug (`skincare`). Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/category?category=cat150006" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/category/products List Sephora category products Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/category/products/get.mdx SDK: client.sephora.getCategoryProducts({ category: "cat150006" }) Parameters: - category (required, string) - Category id (`cat150006`), category page URL (`https://www.sephora.com/shop/skincare`) or its slug (`skincare`). - sort (optional, string, enum: relevance | bestselling | top_rated | newest | price_high_to_low | price_low_to_high) - Order of the products: `relevance` (default), `bestselling`, `top_rated`, `newest`, `price_high_to_low` or `price_low_to_high`. - limit (optional, integer) - Products per page, 1 to 60. Default: 60. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. It only works with the same filters. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/category/products?category=cat150006" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/brands List Sephora brands Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/brands/get.mdx SDK: client.sephora.listBrands() Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/brands" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/brand/products List Sephora brand products Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/brand/products/get.mdx SDK: client.sephora.getBrandProducts({ brand: "The Ordinary" }) Parameters: - brand (required, string) - Brand name as Sephora shows it (`rhode`, `The Ordinary`), its slug (`the-ordinary`) or brand page URL (`https://www.sephora.com/brand/the-ordinary`). Case does not matter. - sort (optional, string, enum: relevance | bestselling | top_rated | newest | price_high_to_low | price_low_to_high) - Order of the products: `relevance` (default), `bestselling`, `top_rated`, `newest`, `price_high_to_low` or `price_low_to_high`. - limit (optional, integer) - Products per page, 1 to 60. Default: 60. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. It only works with the same filters. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/brand/products?brand=The%20Ordinary" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/stores List Sephora stores Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/stores/get.mdx SDK: client.sephora.listStores({ country: "US" }) Parameters: - country (optional, string, enum: US | CA) - Only stores in this country: `US` or `CA`. Default: both. - region (optional, string) - Only stores in this state or province, by code (`CA`, `ON`) or name (`California`, `Ontario`), as `/v1/sephora/store` gives it. Case does not matter. - limit (optional, integer) - Stores per page, 1 to 500. Default: 100. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. It only works with the same filters. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/stores?country=US" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/sephora/store Get Sephora store Credit cost: 1 credit. Failed requests are free. Found, empty and not-found answers are all charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/sephora/store/get.mdx SDK: client.sephora.getStore({ store: "centerra" }) Parameters: - store (required, string) - Store slug (`centerra`) or store page URL (`https://www.sephora.com/happening/stores/centerra`). Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/sephora/store?store=centerra" \ -H "x-api-key: YOUR_API_KEY"