Référence API
Documentation
Tout pour intégrer The Beauty API : 260 000 produits, 26 000 fiches d’ingrédients et 260 000 images de produits hébergées, accessibles par une interface JSON uniforme.
Ajoutez ces instructions en anglais à votre fichier CLAUDE.md, AGENTS.md ou aux règles de votre éditeur pour aider votre assistant à utiliser l’API. Également disponibles sur https://thebeautyapi.com/agent.md.
Afficher les 23 lignes ▾Masquer ▴
# The Beauty API: instructions for coding agents
Base URL: https://api.thebeautyapi.com/v1 (JSON over HTTPS)
Auth: send the header x-api-key: $BEAUTY_API_KEY on every /v1 request. Keep the key in an environment variable, never in code or in this file.
Reference: https://thebeautyapi.com/docs.md | Spec: https://api.thebeautyapi.com/openapi.json | Keys: https://thebeautyapi.com/dashboard
## Endpoints
- Health: GET /health (no key)
- Search products: GET /v1/products/search?q=&page=
- Filter products: GET /v1/products?category=&brand=&origin=&fragrance_free=&alcohol_free=¶ben_free=&sulfate_free=&silicone_free=&has_ingredient=&excludes_ingredient=&page=
- Get a product: GET /v1/products/{id}
- Batch products: POST /v1/products/batch (body {"ids": [uuid, ...]}, max 50)
- Search ingredients: GET /v1/ingredients/search?q=&page=
- Get an ingredient: GET /v1/ingredients/{id}
## Rules
1. Find a product with search, then fetch the full record with GET /v1/products/{id}. Search and filter return slim records (id, brand, name, category, image_url); detail and batch return the full product record. See Ingredients data in the reference for the flat, sectioned and component formats.
2. Every word in q must appear in the product's brand or name, in any order. Send the brand plus the distinctive part of the name ("CeraVe Moisturizing Cream"), never a full retail title. Case, accents and punctuation are ignored; the last word may be partial.
3. When pagination.total is 0 the response carries a no_match object: drop the word no_match.hint names and retry. An empty result does not mean the brand is missing.
4. Pages hold 20 results; page runs 1 to 51 and anything higher returns 400. Read pagination.total and pagination.has_more; above 1,020 matches, narrow with filters instead of paging.
5. Batch takes up to 50 ids and is billed per item (50 ids = 50 calls); unknown ids come back as null in the same positions.
6. Errors are JSON {statusCode, error, message} and message says what to change. 403 is a missing or revoked key. 429 is the rate limit; no rate-limit headers are sent, so back off exponentially.
7. image_url can be null.
8. Deduplication aliases resolve older product and ingredient IDs to surviving records. Unknown or retired ingredient IDs return 400 in ingredient filters.
Sur cette page
Présentation
The Beauty API est une API REST donnant accès à un catalogue normalisé de produits de beauté et d’ingrédients : 260 000 produits, 26 000 fiches d’ingrédients et 5.5 million occurrences d’ingrédients, actualisés tous les deux mois. Tous les points d’accès acceptent et renvoient du JSON via HTTPS. Les réponses sont compressées (brotli ou gzip) lorsque votre client envoie l’en-tête Accept-Encoding.
https://api.thebeautyapi.com/v1L’API décrit ses propres points d’accès. Une requête à sa racine ou à /v1 renvoie un document de découverte avec la méthode, l’URL et le résumé de chaque point d’accès, ainsi que les liens vers cette documentation et la spécification OpenAPI 3.1 en anglais, servie à /openapi.json. Ces deux documents sont accessibles sans clé API : les agents et générateurs de SDK peuvent partir de la seule URL de base.
curl https://api.thebeautyapi.com/ # endpoints, docs_url, openapi_url, authentication
curl https://api.thebeautyapi.com/openapi.json # OpenAPI 3.1 documentLa version anglaise de cette référence est également disponible dans un fichier Markdown unique, avec un index pour les agents. Un agent de développement peut ainsi la lire en une requête, sans analyser cette page HTML.
Authentification
Chaque requête sous /v1 nécessite une clé API dans l’en-tête x-api-key. Vous gérez vos clés dans le tableau de bord : jusqu’à 2 clés actives par compte, que vous pouvez créer, afficher et révoquer à tout moment. Une clé absente, invalide ou révoquée renvoie 403. Seuls /health, le document de découverte et /openapi.json sont ouverts.
curl "https://api.thebeautyapi.com/v1/products/search?q=retinol&page=1" \
-H "x-api-key: YOUR_API_KEY"Gardez vos clés API secrètes. Appelez l’API depuis votre serveur et n’intégrez jamais de clé dans le code d’un navigateur ou d’une application mobile : toute personne qui y accède peut consommer votre quota.
Démarrage rapide
Définissez votre clé dans une variable d’environnement, puis recherchez dans le catalogue avec le langage de votre choix.
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const { results, pagination } = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/search",
params={"q": "niacinamide", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json()Points d’accès
Produits
Recherchez un produit par nom, filtrez le catalogue selon ses caractéristiques, puis consultez sa fiche complète et ses ingrédients. La recherche par code-barres et les requêtes par lot renvoient la même fiche complète.
/v1/products/searchRechercher des produits
Recherchez par marque et nom de produit. Chaque mot de q doit figurer dans la marque ou le nom, quel que soit l’ordre. La casse, les accents et la ponctuation sont ignorés (Dr.Jart+ devient dr jart). Le dernier mot peut être incomplet (cera trouve CeraVe), ce qui permet l’autocomplétion. La réponse contient des fiches résumées ; consultez ensuite le point d’accès du produit pour obtenir sa fiche complète.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| q | URL | string | Oui | Texte de recherche, de 1 à 200 caractères. Indiquez la marque et la partie distinctive du nom, plutôt que le titre commercial complet. |
| page | URL | integer | Non | Numéro de page, de 1 à 51. Facultatif, 1 par défaut. Chaque page contient 20 résultats. |
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/search",
params={"q": "niacinamide", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"results": [
{
"id": "99f9c56e-23ab-5385-8789-7266738c9ad6",
"brand": "Mumuso",
"name": "Niacinamide",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/99f9c56e-23ab-5385-8789-7266738c9ad6.jpg"
},
{
"id": "b7f8c8de-ea5c-5f63-922d-69a299efe7e1",
"brand": "SkinABCs",
"name": "Niacinamide",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/b7f8c8de-ea5c-5f63-922d-69a299efe7e1.jpg"
}
],
"pagination": {
"page": 1,
"has_more": true,
"total": 2009
}
}| Recherche | Résultat |
|---|---|
| q=CeraVe Moisturizing Cream | ✓CeraVe Moisturizing Cream et ses variantes (Baby, Intensive, Psoriasis, For Dry To Very Dry Skin…). |
| q=CeraVe Moisturizing Cream Daily Face and Body Moisturizer for Dry Skin | ✗Aucun produit enregistré ne correspond à tous les termes. no_match.hint indique le mot le moins spécifique à retirer ; no_match.terms donne le nombre de correspondances de chaque mot. |
| q=Laneige sleeping mask | ✓Tous les masques de nuit LANEIGE (Water, Lip, Cica, Time Freeze…). |
À savoir :
- 01Un tableau
resultsvide signifie qu’aucun produit ne contient tous les mots demandés. Cela ne signifie pas que la marque est absente. - 02Lorsque
totalvaut 0, la réponse contientno_match:hintindique le mot à retirer ettermsle nombre de correspondances de chaque mot. Retirez le mot sans correspondance (faute de frappe, numéro de ligne d’un reçu) ou le moins spécifique (serum, cream, SPF), puis réessayez. - 03Utilisez dès le départ la marque et un nom court, jamais le titre complet d’une fiche commerciale.
- 04Tout caractère autre qu’une lettre ou un chiffre sépare les mots :
Oil-Freedevientoiletfree,10%devient10. Seuls les 10 premiers mots comptent. - 05Une recherche sans lettre ni chiffre renvoie
400.
/v1/productsFiltrer les produits
Trouvez des produits par catégorie, marque, pays d’origine, caractéristiques de formulation et composition. Tous les filtres se combinent avec AND : chaque condition doit être satisfaite. La réponse contient les mêmes fiches résumées que la recherche.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| category | URL | string | Non | Correspondance exacte, sensible à la casse, avec la catégorie enregistrée : skincare, suncare, makeup, haircare, body/bath, fragrance, other, deodorants, oral-care, tools_accessories ou devices. Toute autre valeur renvoie une page vide avec no_match, sans erreur. |
| brand | URL | string | Non | Nom de marque. La casse, les accents, la ponctuation et les espaces sont ignorés : supergoop trouve Supergoop!, sk ii trouve SK-II. Les fautes d’orthographe ne sont pas corrigées ; utilisez la recherche pour trouver le nom enregistré. |
| origin | URL | string | Non | Correspondance exacte, sensible à la casse, avec le pays d’origine de la marque enregistré, par exemple USA, South Korea, France, United Kingdom. Cette information est inconnue pour ~57% des produits, qui ne correspondent à aucune valeur d’origin. |
| fragrance_free | URL | boolean | Non | Caractéristiques de formulation. Également disponibles : alcohol_free, paraben_free, sulfate_free, silicone_free. |
| has_ingredient | URL | uuid | Non | Uniquement les produits contenant cet ingrédient. Les identifiants proviennent des points d’accès aux ingrédients. |
| excludes_ingredient | URL | uuid list | Non | Produits ne contenant aucun de ces ingrédients. Jusqu’à 10 identifiants séparés par des virgules. |
| page | URL | integer | Non | Numéro de page, de 1 à 51. Facultatif, 1 par défaut. Chaque page contient 20 résultats. |
curl "https://api.thebeautyapi.com/v1/products?category=skincare&fragrance_free=true&has_ingredient=a1526dea-37d1-5904-9106-be583378339b&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products?category=skincare&fragrance_free=true&has_ingredient=a1526dea-37d1-5904-9106-be583378339b&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products",
params={"category": "skincare", "fragrance_free": True, "has_ingredient": "a1526dea-37d1-5904-9106-be583378339b", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"results": [
{
"id": "a70e8e5b-5905-57f9-8e8a-acd9feaa43c2",
"brand": "IOPE",
"name": "Bio Essence Intensive Conditioning",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/a70e8e5b-5905-57f9-8e8a-acd9feaa43c2.jpg"
},
{
"id": "7ebe8574-c405-51e0-a597-f9ce33bc7b95",
"brand": "Biologique Recherche",
"name": "Lotion P50 T",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/7ebe8574-c405-51e0-a597-f9ce33bc7b95.jpg"
}
],
"pagination": {
"page": 1,
"has_more": true,
"total": 11295
}
}À savoir :
- 01Un identifiant d’ingrédient inconnu ou retiré renvoie
400dans les deux filtres d’ingrédients. Les alias enregistrés renvoient à l’ingrédient conservé après dédoublonnage ; voir Données sur les ingrédients. - 02Lorsque
totalvaut 0,no_match.hintexplique pourquoi aucun produit ne correspond aux filtres fournis.
/v1/products/{id}Obtenir un produit
La fiche complète : marque, catégorie, origine, caractéristiques de formulation, URL de l’image hébergée et ingrédients dans l’ordre de l’étiquette, avec les noms, fonctions, évaluations et identifiants chimiques disponibles.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| id | Chemin | uuid | Oui | Identifiant du produit. |
curl https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23 \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23",
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"id": "06d9476a-397b-5f61-abc8-640b30a9ae23",
"brand": "The Ordinary",
"name": "Niacinamide 10% + Zinc 1%",
"image_url": "https://images.thebeautyapi.com/06d9476a-397b-5f61-abc8-640b30a9ae23.jpg",
"category": "skincare",
"origin": "Canada",
"contains_fragrance": false,
"contains_drying_alcohol": false,
"contains_parabens": false,
"contains_sulfates": false,
"contains_silicones": false,
"product_type": "unknown",
"subcategory": "Serum",
"size": null,
"packaging": null,
"pack_count": null,
"shade_name": null,
"benefits": null,
"directions": null,
"warnings": null,
"ingredients_raw": "Aqua (Water), Niacinamide 10.0%, Pentylene Glycol, Zinc Pca 1.0%, Dimethyl Isosorbide, Tamarindus Indica Seed Gum, Xanthan Gum, Isoceteth-20, Ethoxydiglycol, Phenoxyethanol, Chlorphenesin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": ["solvent"],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Niacinamide 10.0%",
"concentration": 10,
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}
]
}À savoir :
- 01Les fiches complètes comprennent
ingredients_rawau niveau du produit, ses métadonnées et des compositions sous forme de liste simple, de sections ou de composants. Certains ingrédients peuvent ne pas être associés à une fiche du dictionnaire. Les champs du dictionnaire valent alors null. Les indicateurs non renseignés valent également null. Voir Données sur les ingrédients. - 02Les alias de dédoublonnage préservent les anciens identifiants : une recherche par alias renvoie le produit conservé et son identifiant.
- 03
concentrationest renseigné uniquement lorsque le fabricant la publie. Elle n’est jamais estimée. - 04Aucune offre n’inclut les codes-barres dans cette réponse. Les offres avec Barcode permettent de retrouver un produit à partir d’un GTIN via la Recherche par code-barres.
/v1/products/barcode/{barcode}Rechercher par code-barres
Retrouvez un produit à partir d’un code scanné ou issu de votre catalogue (UPC-A, EAN-13, GTIN-8/14). La réponse est la même fiche complète que pour Obtenir un produit. Les codes unitaires, de lots et de variantes (teinte, parfum, format d’une même gamme) sont pris en charge. Les formes GTIN complétées par des zéros en tête (UPC-A, EAN-13, GTIN-14) d’un même code sont équivalentes. Réservé aux offres avec Barcode.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| barcode | Chemin | string | Oui | De 8 à 14 chiffres, sans espace ni tiret (^[0-9]{8,14}$). |
curl https://api.thebeautyapi.com/v1/products/barcode/769915195941 \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/barcode/769915195941",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/barcode/769915195941",
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"id": "06d9476a-397b-5f61-abc8-640b30a9ae23",
"brand": "The Ordinary",
"name": "Niacinamide 10% + Zinc 1%",
"image_url": "https://images.thebeautyapi.com/06d9476a-397b-5f61-abc8-640b30a9ae23.jpg",
"category": "skincare",
"origin": "Canada",
"contains_fragrance": false,
"contains_drying_alcohol": false,
"contains_parabens": false,
"contains_sulfates": false,
"contains_silicones": false,
"product_type": "unknown",
"subcategory": "Serum",
"size": null,
"packaging": null,
"pack_count": null,
"shade_name": null,
"benefits": null,
"directions": null,
"warnings": null,
"ingredients_raw": "Aqua (Water), Niacinamide 10.0%, Pentylene Glycol, Zinc Pca 1.0%, Dimethyl Isosorbide, Tamarindus Indica Seed Gum, Xanthan Gum, Isoceteth-20, Ethoxydiglycol, Phenoxyethanol, Chlorphenesin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": ["solvent"],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Niacinamide 10.0%",
"concentration": 10,
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}
]
}À savoir :
- 01La réponse ne fournit jamais la liste des codes-barres d’un produit. L’API retrouve un produit à partir d’un code ; elle ne permet pas d’énumérer les codes. La liste complète des GTIN est fournie uniquement avec la base sous licence.
- 02
403si votre offre n’inclut pas cette fonction (message : “Your current plan does not include Barcode Lookup access.”).404en l’absence de correspondance.400si le format est incorrect. - 03Compte pour 1 appel facturé.
- 04Environ 61% du catalogue possède actuellement un code ; cette couverture augmente au fil des mises à jour.
/v1/products/batchObtenir plusieurs produits
Récupérez jusqu’à 50 fiches complètes en une requête. Le tableau de réponse conserve la longueur et l’ordre des identifiants envoyés ; chaque identifiant inconnu est représenté par null.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| ids | Corps | uuid[] | Oui | De 1 à 50 identifiants de produits. |
curl -X POST https://api.thebeautyapi.com/v1/products/batch \
-H "x-api-key: $BEAUTY_API_KEY" \
-H "content-type: application/json" \
-d '{"ids": ["06d9476a-397b-5f61-abc8-640b30a9ae23", "00000000-0000-0000-0000-000000000000"]}'const res = await fetch("https://api.thebeautyapi.com/v1/products/batch", {
method: "POST",
headers: {
"x-api-key": process.env.BEAUTY_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({ ids: ["06d9476a-397b-5f61-abc8-640b30a9ae23", "00000000-0000-0000-0000-000000000000"] }),
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.thebeautyapi.com/v1/products/batch",
json={"ids": ["06d9476a-397b-5f61-abc8-640b30a9ae23", "00000000-0000-0000-0000-000000000000"]},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json()[
{
"id": "06d9476a-397b-5f61-abc8-640b30a9ae23",
"brand": "The Ordinary",
"name": "Niacinamide 10% + Zinc 1%",
"image_url": "https://images.thebeautyapi.com/06d9476a-397b-5f61-abc8-640b30a9ae23.jpg",
"category": "skincare",
"origin": "Canada",
"contains_fragrance": false,
"contains_drying_alcohol": false,
"contains_parabens": false,
"contains_sulfates": false,
"contains_silicones": false,
"product_type": "unknown",
"subcategory": "Serum",
"size": null,
"packaging": null,
"pack_count": null,
"shade_name": null,
"benefits": null,
"directions": null,
"warnings": null,
"ingredients_raw": "Aqua (Water), Niacinamide 10.0%, Pentylene Glycol, Zinc Pca 1.0%, Dimethyl Isosorbide, Tamarindus Indica Seed Gum, Xanthan Gum, Isoceteth-20, Ethoxydiglycol, Phenoxyethanol, Chlorphenesin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": ["solvent"],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Niacinamide 10.0%",
"concentration": 10,
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}
]
},
null
]À savoir :
- 01Chaque élément non nul utilise le même format que la fiche d’un produit, y compris les structures d’ingrédients et les alias décrits dans Données sur les ingrédients.
- 02Envoyez du JSON avec
Content-Type: application/json. Un type de contenu absent ou non reconnu renvoie415. - 03Un corps JSON invalide ou un champ
idsabsent, vide, contenant plus de 50 éléments ou des valeurs autres que des UUID renvoie400. - 04Avec une offre payante, la facturation se fait par élément : 50 identifiants comptent pour 50 appels. L’en-tête de réponse
X-Item-Countindique le nombre facturable. - 05Pour les limites de débit et le quota de 100 requêtes de l’essai, un lot compte comme une seule requête. Aucun dépassement n’est facturé pendant l’essai.
Points d’accès
Ingrédients
Recherchez par nom INCI ou synonyme, puis consultez la fiche complète : fonctions, indices d’irritation et de comédogénicité, identifiants chimiques. Utilisez les identifiants dans les filtres de produits.
/v1/ingredients/searchRechercher des ingrédients
Recherchez parmi les 26 000 fiches du dictionnaire par nom INCI normalisé ou synonyme connu. Utilisez les identifiants obtenus dans les filtres de produits ou pour consulter la fiche d’un ingrédient.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| q | URL | string | Oui | Texte de recherche, de 1 à 200 caractères. |
| page | URL | integer | Non | Numéro de page, de 1 à 51. Facultatif, 1 par défaut. Chaque page contient 20 résultats. |
curl "https://api.thebeautyapi.com/v1/ingredients/search?q=niacinamide&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/ingredients/search?q=niacinamide&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/ingredients/search",
params={"q": "niacinamide", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"results": [
{
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"other_names": "vitamin B3, nicotinamide",
"rating": "direct actives"
},
{
"id": "e0788047-91e6-5041-aedc-54d2d8c4c025",
"name": "Niacinamide Retinoate",
"other_names": null,
"rating": null
},
{
"id": "d38b26f6-cdf1-53fd-ae1b-b0de434064af",
"name": "Niacinamide (NIA-114™)",
"other_names": null,
"rating": null
},
{
"id": "83b58d16-4775-5b15-91cd-04e1ff64be99",
"name": "Niacinamide Polypeptide",
"other_names": null,
"rating": null
},
{
"id": "dd34f14a-7142-5884-bb1e-dd78cc03ef84",
"name": "Niacinamide (Soy-Derived)",
"other_names": null,
"rating": null
},
{
"id": "80df0bd2-443b-590c-a7fd-45149f9034f6",
"name": "Niacinamide/Yeast Polypeptide",
"other_names": null,
"rating": null
},
{
"id": "5461bbea-efdb-567a-9ce5-4c9fdc3b22c2",
"name": "Niacinamide (Skin-Conditioner)",
"other_names": null,
"rating": null
},
{
"id": "e24c8441-d4c6-5d35-aeb1-d215a506a899",
"name": "Methyl Niacinamide Chloride",
"other_names": null,
"rating": null
},
{
"id": "a87fb600-b56c-52dc-b13e-e86acb56ff4b",
"name": "Naturally Derived Niacinamide",
"other_names": null,
"rating": null
},
{
"id": "f53466cb-ee15-575e-b226-79c4ad90a6d9",
"name": "Biotin/Folic Acid/Cyanocobalamin/Niacinamide/Pantothenic Acid/Pyridoxine/Riboflavin/Thiamine/Yeast Polypeptides",
"other_names": null,
"rating": null
}
],
"pagination": {
"page": 1,
"has_more": false,
"total": 10
}
}/v1/ingredients/{id}Obtenir un ingrédient
La fiche scientifique complète d’un ingrédient : nom normalisé, synonymes, fonctions, indices d’irritation et de comédogénicité, identifiants CAS, CE, IUPAC et Ph. Eur.
| Paramètre | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| id | Chemin | uuid | Oui | Identifiant de l’ingrédient. |
curl https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b",
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}À savoir :
- 01Les alias enregistrés renvoient à la fiche conservée après dédoublonnage. Un identifiant retiré sans remplaçant renvoie
410; un identifiant inconnu renvoie404.
Points d’accès
Référence
État du service et fonctionnement commun aux points d’accès : pagination, erreurs, limites des offres, images, codes-barres et versions.
/healthÉtat du service
Vérifie que le service répond et indique la taille et la date de préparation du catalogue actuellement accessible via l’API. Le champ built_at (AAAA-MM-JJ, UTC) indique quand cette version a été préparée : les mises à jour de l’API suivent leur propre calendrier, indépendamment de la base téléchargeable (voir l’historique). Aucune clé API n’est nécessaire, comme pour le document de découverte à la racine et la spécification /openapi.json.
Aucune authentification nécessaire.
curl https://api.thebeautyapi.com/healthconst res = await fetch("https://api.thebeautyapi.com/health");
const data = await res.json();import requests
res = requests.get("https://api.thebeautyapi.com/health")
data = res.json(){
"status": "ok",
"products": 272761,
"ingredients": 26420,
"built_at": "2026-11-09"
}Pagination
Les points d’accès qui renvoient des listes fournissent 20 résultats par page. Envoyez page (de 1 à 51) et consultez l’objet pagination ; poursuivez tant que has_more vaut true. total compte les correspondances sur l’ensemble des pages, ce qui permet de distinguer un résultat unique de plusieurs candidats. Au-delà de la page 51, l’API renvoie 400. Si le total dépasse 1 020, soit 20 × 51, affinez la recherche avec des filtres.
"pagination": { "page": 2, "has_more": true, "total": 47 }Erreurs
Les erreurs utilisent les codes HTTP habituels et un corps JSON uniforme :
{
"statusCode": 404,
"error": "Not Found",
"message": "No product with id 00000000-0000-4000-8000-000000000000"
}Basez votre traitement sur statusCode. Le champ message explique l’erreur et indique quoi corriger lors du diagnostic. Par exemple, un paramètre non accepté renvoie la liste des paramètres autorisés et le point d’accès à utiliser :
{
"statusCode": 400,
"error": "Bad Request",
"message": "Unknown query parameters 'name', 'limit'. GET /v1/products accepts: category, brand, origin, fragrance_free, alcohol_free, paraben_free, sulfate_free, silicone_free, has_ingredient, excludes_ingredient, page. To find products by name, use GET /v1/products/search?q=<brand and product name>. Pages are fixed at 20 results; use page=2, page=3, … for more."
}| Statut | Signification |
|---|---|
| 400 | La requête ne peut pas aboutir : paramètre non accepté, identifiant ou code-barres mal formé, ingrédient inconnu ou retiré dans un filtre, page supérieure à 51, recherche vide ou trop longue, ou corps de lot invalide. Le message indique le champ concerné et, pour un paramètre inconnu, la liste des paramètres acceptés. Corrigez la requête avant de la renvoyer. |
| 402 | Essai expiré ou paiement nécessaire. Vérifiez votre situation de paiement dans le tableau de bord avant de réessayer. |
| 403 | Clé API absente, invalide ou désactivée, ou recherche par code-barres avec une offre qui ne l’inclut pas. |
| 404 | La requête est bien formée mais ne correspond à rien : aucun produit ou ingrédient avec cet identifiant, aucun produit avec ce code-barres, ou adresse de point d’accès inexistante. Le message reprend l’identifiant ou le code. |
| 410 | Cet identifiant d’ingrédient a été retiré sans remplaçant. Recherchez une fiche actuelle dans le dictionnaire. |
| 413 | Le corps de la requête dépasse 1 Mo. Seul le point d’accès par lot lit un corps ; 50 UUID occupent moins de 3 Ko, donc un lot valide n’atteint pas cette limite. |
| 415 | La requête par lot ne possède pas d’en-tête Content-Type, ou son type n’est pas reconnu. Envoyez Content-Type: application/json. |
| 429 | Quota d’essai épuisé (pour passer à une offre payante, cliquez sur « Convert to paid plan » dans le tableau de bord), limite de débit dépassée ou plafond mensuel atteint. Les offres payantes ont un plafond anti-abus égal à plusieurs fois le quota inclus : dépasser le quota inclus ne bloque pas les appels, les appels supplémentaires sont facturés. Les plafonds de la passerelle sont réinitialisés le 1er du mois (UTC) ; les quotas payants suivent votre mois de facturation. Le quota d’essai ne se réinitialise pas. Les requêtes d’essai réussies comprennent X-Trial-Requests-Remaining. Espacez les nouvelles tentatives en cas de limite de débit ; utilisez le tableau de bord si l’essai est épuisé. |
| 500 | Erreur interne de notre côté. Vous pouvez réessayer. |
| 503 | La vérification de l’accès est temporairement indisponible. Réessayez après un délai, en espaçant les tentatives. |
| 504 | Le serveur d’origine n’a pas répondu à temps. Vous pouvez réessayer en espaçant les tentatives. |
Limites de débit et quotas
Les nouveaux comptes bénéficient de sept jours d’essai et de 100 requêtes au total, partagées entre toutes leurs clés. Une fois ce quota atteint, l’API renvoie 429 jusqu’au passage à une offre payante ou à la fin de l’essai. L’essai ne génère aucun dépassement facturé. Les frais mensuels sont prélevés d’avance ; les appels au-delà du quota inclus sont facturés 0,02 $ US chacun à la fin du mois de facturation. Sur les offres payantes, chaque élément demandé dans un lot compte pour un appel ; pendant l’essai, un lot compte pour une requête. Le quota payant est réinitialisé au début de chaque mois de facturation.
| Offre | Prix | Appels inclus par mois | Limite de débit |
|---|---|---|---|
| Starter | 40 $ US/mois | 10 000 | 10 req/s, pic de 20 |
| Starter + Barcode | 60 $ US/mois | 10 000 | 10 req/s, pic de 20 |
| Pro | 200 $ US/mois | 100 000 | 25 req/s, pic de 50 |
| Pro + Barcode | 300 $ US/mois | 100 000 | 25 req/s, pic de 50 |
Les requêtes au-delà de la limite de débit renvoient 429. Aucun en-tête de limite de débit n’est envoyé : augmentez progressivement le délai entre vos nouvelles tentatives (attente exponentielle).
Données sur les produits
- Les réponses de détail, par lot et par code-barres incluent les champs ci-dessous. Les valeurs absentes sont null.
- Les résultats de recherche et de filtrage contiennent
id,brand,name,categoryetimage_url.
| Champ | Type | Signification |
|---|---|---|
| product_type | string | null | Structure du produit, par exemple un article seul ou un coffret. |
| subcategory | string | null | Classification plus précise au sein de sa catégorie. |
| size | string | null | Contenance ou format déclaré, avec l’unité ou la description du lot. |
| packaging | string | null | Description du conditionnement : flacon, tube, pot, etc. |
| pack_count | integer | null | Nombre d’articles dans le lot, lorsqu’il est connu. |
| shade_name | string | null | Nom de la teinte indiqué pour le produit. |
| benefits | string | null | Bénéfices annoncés du produit, lorsqu’ils sont disponibles. |
| directions | string | null | Conseils d’utilisation. Le texte peut contenir des sauts de ligne. |
| warnings | string | null | Précautions fournies avec le produit. Le texte peut contenir des sauts de ligne. |
| ingredients_raw | string | null | Texte brut des ingrédients de la fiche produit ; voir les données sur les ingrédients ci-dessous. |
Données sur les ingrédients
Les listes d’ingrédients peuvent se présenter sous trois formes :
ingredients: une liste ordonnée unique.ingredient_sections: des sections nommées, chacune avec sa propre liste.components: les articles d’un coffret, chacun avec une liste ou des sections.- Chaque produit utilise une seule structure ; les autres champs sont omis. Une liste indisponible vaut null ; les autres listes restent accessibles.
Champs et valeurs
position: commence à zéro dans chaque liste d’ingrédients, de section ou de composant.label_name: libellé de l’ingrédient avec corrections orthographiques ; il peut différer du nom normalisé.concentration: pourcentage déclaré, ou null.- Les libellés sans correspondance conservent leur position et leur texte, avec
idet les champs du dictionnaire à null. Les ingrédients reconnus peuvent avoir un tableaufunctionsvide. - Les identifiants d’ingrédients de l’API sont des UUID. Les valeurs
ingredient_idde la base téléchargeable sont des entiers. contains_*: true, false ou null (inconnu). Le champheadingd’une section et le champnamed’un composant peuvent aussi être nuls.- Les titres reconnus sont normalisés en Ingredients, Active ingredients, Inactive ingredients, Medicinal ingredients, Non-medicinal ingredients ou May contain. Les autres titres conservent leur libellé.
Texte brut des ingrédients
ingredients_raw: texte des ingrédients issu de la fiche produit, fourni en complément des listes structurées. Il n’est pas répété dans chaque section ou composant.- Le texte d’origine et ses sauts de ligne sont conservés lorsqu’ils sont disponibles. Un texte absent vaut null.
Exemples de réponses API
Ces exemples montrent comment les ingrédients sont présentés dans les réponses de l’API. Sélectionnez un format pour le consulter.
{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Aqua (Water), Glycerin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [ "solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Active ingredients: Zinc Oxide\nInactive ingredients: Aqua (Water), Glycerin",
"ingredient_sections": [
{
"position": 0,
"heading": "Active ingredients",
"ingredients": [
{
"position": 0,
"label_name": "Zinc Oxide",
"concentration": null,
"id": "d6512677-49b1-5505-982d-6c9635b5f4a7",
"name": "Zinc Oxide", "rating": "supporting actives",
"irritancy": "0",
"comedogenicity": "1",
"functions": [
"bulking",
"cosmetic colorant",
"skin protecting",
"uv absorber",
"uv filter"
],
"cas_number": "1314-13-2",
"ec_number": "215-222-5",
"ph_eur_name": "Zinci Oxidum",
"iupac_name": "Zinc Oxide (Ci 77947)",
"other_names": null,
"category": null
}
]
},
{
"position": 1,
"heading": "Inactive ingredients",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [
"solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
}
]
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Cleanser: Aqua (Water), Glycerin\nSerum: Aqua (Water), Glycerin",
"components": [
{
"position": 0,
"name": "Cleanser",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water", "rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [
"solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
},
{
"position": 1,
"name": "Serum",
"ingredient_sections": [
{
"position": 0,
"heading": "Ingredients",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [
"solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
}
]
}
]
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Aqua (Water), Glycerin",
"ingredients": null
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": null,
"ingredients": null
}Identifiants et dédoublonnage
- Les alias de dédoublonnage relient les anciens identifiants de produits et d’ingrédients aux fiches conservées.
- Les recherches de produits, y compris par lot, renvoient le produit conservé et son identifiant. Les recherches et filtres d’ingrédients acceptent également les anciens identifiants et utilisent la fiche conservée.
- Filtres d’ingrédients : tout identifiant inconnu ou retiré entraîne un
400pour l’ensemble de la requête. - Fiche d’ingrédient :
410pour un identifiant retiré sans remplaçant ;404pour un identifiant inconnu.
Fichiers de la base
- JSONL : les mêmes structures d’ingrédients, avec des références
ingredient_idnumériques. - CSV et SQLite :
product_ingredientscontient les listes simples ;product_ingredient_groupscontient les sections et composants ;product_group_ingredientscontient leurs entrées. - Les libellés sans correspondance conservent une ligne avec une référence d’ingrédient nulle.
- Valeurs nulles : SQL NULL dans SQLite ; cellules vides dans les CSV. Les champs CSV entre guillemets préservent les sauts de ligne du texte des ingrédients.
Images des produits
Le champ image_url pointe vers une photographie de produit standardisée sur fond blanc, servie depuis images.thebeautyapi.com. Nous hébergeons 260 000 images que vous pouvez afficher directement dans votre interface, sans téléchargement ni réhébergement. Un petit nombre de produits n’a pas de photographie ; leur champ image_url vaut null.
Codes-barres
Les codes-barres servent de clé de recherche, et ne sont pas un champ de réponse. Avec une offre Barcode, GET /v1/products/barcode/{barcode} retrouve le produit associé à un UPC-A, EAN-13 ou GTIN-8/14 et renvoie sa fiche standard. Aucune réponse ne liste les codes d’un produit, quelle que soit l’offre : détail, lot, recherche et filtres ont le même format avec ou sans accès Barcode. Les codes unitaires, de lots et de variantes (teinte, parfum, format d’une même gamme) sont pris en charge ; un UPC-A et sa forme EAN-13 complétée par un zéro sont équivalents. Environ 61% du catalogue possède au moins un code. Si vous avez besoin des codes eux-mêmes, la base sous licence fournit une liste gtin14 par produit.
Gestion des versions
L’API utilise le chemin /v1. Vos clients doivent ignorer les champs de réponse supplémentaires. Les produits peuvent présenter une liste simple d’ingrédients, des sections ou des composants, avec des champs pouvant être nuls. La section Données sur les ingrédients explique comment traiter ces différents formats.
Les mises à jour des données et de l’API figurent dans l’historique.
Essayer avec Postman
Pour essayer les points d’accès avant d’écrire du code, importez notre collection Postman, renseignez votre clé API dans une variable et envoyez les requêtes. La collection comprend aussi un dossier de requêtes volontairement invalides pour voir les réponses 400, 403 et 404.
Commencez votre intégration
Commencez par sept jours d’essai avec 100 requêtes. Les offres payantes commencent à 40 $ US/mois avec 10 000 appels inclus.