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.

Pour les assistants de développement

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 ▾
# 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=&paraben_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.

URL de base
https://api.thebeautyapi.com/v1

L’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.

Découvertecurl
curl https://api.thebeautyapi.com/              # endpoints, docs_url, openapi_url, authentication
curl https://api.thebeautyapi.com/openapi.json  # OpenAPI 3.1 document

La 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.

Requête authentifiéecurl
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.

Exemple
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
  -H "x-api-key: $BEAUTY_API_KEY"

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.

GET/v1/products/search

Rechercher 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ètreEmplacementTypeObligatoireDescription
qURLstringOuiTexte de recherche, de 1 à 200 caractères. Indiquez la marque et la partie distinctive du nom, plutôt que le titre commercial complet.
pageURLintegerNonNuméro de page, de 1 à 51. Facultatif, 1 par défaut. Chaque page contient 20 résultats.
Requête
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OK (2 premiers résultats affichés)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
  }
}
RechercheRé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 :

  1. 01Un tableau results vide signifie qu’aucun produit ne contient tous les mots demandés. Cela ne signifie pas que la marque est absente.
  2. 02Lorsque total vaut 0, la réponse contient no_match : hint indique le mot à retirer et terms le 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.
  3. 03Utilisez dès le départ la marque et un nom court, jamais le titre complet d’une fiche commerciale.
  4. 04Tout caractère autre qu’une lettre ou un chiffre sépare les mots : Oil-Free devient oil et free, 10% devient 10. Seuls les 10 premiers mots comptent.
  5. 05Une recherche sans lettre ni chiffre renvoie 400.
GET/v1/products

Filtrer 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ètreEmplacementTypeObligatoireDescription
categoryURLstringNonCorrespondance 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.
brandURLstringNonNom 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é.
originURLstringNonCorrespondance 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_freeURLbooleanNonCaractéristiques de formulation. Également disponibles : alcohol_free, paraben_free, sulfate_free, silicone_free.
has_ingredientURLuuidNonUniquement les produits contenant cet ingrédient. Les identifiants proviennent des points d’accès aux ingrédients.
excludes_ingredientURLuuid listNonProduits ne contenant aucun de ces ingrédients. Jusqu’à 10 identifiants séparés par des virgules.
pageURLintegerNonNuméro de page, de 1 à 51. Facultatif, 1 par défaut. Chaque page contient 20 résultats.
Requête
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"
200 OK (2 premiers résultats affichés)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 :

  1. 01Un identifiant d’ingrédient inconnu ou retiré renvoie 400 dans 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.
  2. 02Lorsque total vaut 0, no_match.hint explique pourquoi aucun produit ne correspond aux filtres fournis.
GET/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ètreEmplacementTypeObligatoireDescription
idCheminuuidOuiIdentifiant du produit.
Requête
curl https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23 \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OK (2 premiers ingrédients affichés)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 :

  1. 01Les fiches complètes comprennent ingredients_raw au 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.
  2. 02Les alias de dédoublonnage préservent les anciens identifiants : une recherche par alias renvoie le produit conservé et son identifiant.
  3. 03concentration est renseigné uniquement lorsque le fabricant la publie. Elle n’est jamais estimée.
  4. 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.
GET/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ètreEmplacementTypeObligatoireDescription
barcodeCheminstringOuiDe 8 à 14 chiffres, sans espace ni tiret (^[0-9]{8,14}$).
Requête
curl https://api.thebeautyapi.com/v1/products/barcode/769915195941 \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OK (2 premiers ingrédients affichés)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 :

  1. 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.
  2. 02403 si votre offre n’inclut pas cette fonction (message : “Your current plan does not include Barcode Lookup access.”). 404 en l’absence de correspondance. 400 si le format est incorrect.
  3. 03Compte pour 1 appel facturé.
  4. 04Environ 61% du catalogue possède actuellement un code ; cette couverture augmente au fil des mises à jour.
POST/v1/products/batch

Obtenir 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ètreEmplacementTypeObligatoireDescription
idsCorpsuuid[]OuiDe 1 à 50 identifiants de produits.
Requête
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"]}'
200 OK (2 premiers ingrédients affichés)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 :

  1. 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.
  2. 02Envoyez du JSON avec Content-Type: application/json. Un type de contenu absent ou non reconnu renvoie 415.
  3. 03Un corps JSON invalide ou un champ ids absent, vide, contenant plus de 50 éléments ou des valeurs autres que des UUID renvoie 400.
  4. 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-Count indique le nombre facturable.
  5. 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.

GET/v1/ingredients/search

Rechercher 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ètreEmplacementTypeObligatoireDescription
qURLstringOuiTexte de recherche, de 1 à 200 caractères.
pageURLintegerNonNuméro de page, de 1 à 51. Facultatif, 1 par défaut. Chaque page contient 20 résultats.
Requête
curl "https://api.thebeautyapi.com/v1/ingredients/search?q=niacinamide&page=1" \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OKjson
{
  "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
  }
}
GET/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ètreEmplacementTypeObligatoireDescription
idCheminuuidOuiIdentifiant de l’ingrédient.
Requête
curl https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OKjson
{
  "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 :

  1. 01Les alias enregistrés renvoient à la fiche conservée après dédoublonnage. Un identifiant retiré sans remplaçant renvoie 410 ; un identifiant inconnu renvoie 404.

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.

GET/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.

Requête
curl https://api.thebeautyapi.com/health
200 OKjson
{
  "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.

Objet de paginationjson
"pagination": { "page": 2, "has_more": true, "total": 47 }

Erreurs

Les erreurs utilisent les codes HTTP habituels et un corps JSON uniforme :

Corps d’une erreurjson
{
  "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 :

Erreur de validationjson
{
  "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."
}
StatutSignification
400La 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.
402Essai expiré ou paiement nécessaire. Vérifiez votre situation de paiement dans le tableau de bord avant de réessayer.
403Clé API absente, invalide ou désactivée, ou recherche par code-barres avec une offre qui ne l’inclut pas.
404La 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.
410Cet identifiant d’ingrédient a été retiré sans remplaçant. Recherchez une fiche actuelle dans le dictionnaire.
413Le 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.
415La 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.
429Quota 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é.
500Erreur interne de notre côté. Vous pouvez réessayer.
503La vérification de l’accès est temporairement indisponible. Réessayez après un délai, en espaçant les tentatives.
504Le 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.

OffrePrixAppels inclus par moisLimite de débit
Starter40 $ US/mois10 00010 req/s, pic de 20
Starter + Barcode60 $ US/mois10 00010 req/s, pic de 20
Pro200 $ US/mois100 00025 req/s, pic de 50
Pro + Barcode300 $ US/mois100 00025 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, category et image_url.
ChampTypeSignification
product_typestring | nullStructure du produit, par exemple un article seul ou un coffret.
subcategorystring | nullClassification plus précise au sein de sa catégorie.
sizestring | nullContenance ou format déclaré, avec l’unité ou la description du lot.
packagingstring | nullDescription du conditionnement : flacon, tube, pot, etc.
pack_countinteger | nullNombre d’articles dans le lot, lorsqu’il est connu.
shade_namestring | nullNom de la teinte indiqué pour le produit.
benefitsstring | nullBénéfices annoncés du produit, lorsqu’ils sont disponibles.
directionsstring | nullConseils d’utilisation. Le texte peut contenir des sauts de ligne.
warningsstring | nullPrécautions fournies avec le produit. Le texte peut contenir des sauts de ligne.
ingredients_rawstring | nullTexte 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 id et les champs du dictionnaire à null. Les ingrédients reconnus peuvent avoir un tableau functions vide.
  • Les identifiants d’ingrédients de l’API sont des UUID. Les valeurs ingredient_id de la base téléchargeable sont des entiers.
  • contains_* : true, false ou null (inconnu). Le champ heading d’une section et le champ name d’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.

Exemple
GEThttps://api.thebeautyapi.com/v1/products/00000000-0000-4000-8000-000000000001
{
  "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": [
Documentation de l’API

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 400 pour l’ensemble de la requête.
  • Fiche d’ingrédient : 410 pour un identifiant retiré sans remplaçant ; 404 pour un identifiant inconnu.

Fichiers de la base

  • JSONL : les mêmes structures d’ingrédients, avec des références ingredient_id numériques.
  • CSV et SQLite : product_ingredients contient les listes simples ; product_ingredient_groups contient les sections et composants ; product_group_ingredients contient 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.

Lire le guide : tester The Beauty API dans Postman

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.