API-Referenz

Dokumentation

Alles für die Integration von The Beauty API: 260.000 Produkte, 26.000 Inhaltsstoffdatensätze und 260.000 gehostete Produktbilder über eine einheitliche JSON-Schnittstelle.

Für KI-Programmierassistenten

Fügen Sie diese englischen Anweisungen in Ihre CLAUDE.md, AGENTS.md oder Editor-Regeln ein, damit Ihr Assistent die API richtig verwendet. Auch verfügbar unter https://thebeautyapi.com/agent.md.

Alle 23 Zeilen anzeigen ▾
# 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.
Auf dieser Seite

Überblick

The Beauty API ist eine REST-API für einen normalisierten Katalog von Kosmetikprodukten und Inhaltsstoffen: 260.000 Produkte, 26.000 Inhaltsstoffdatensätze und 5,5 million Inhaltsstoffvorkommen, alle zwei Monate aktualisiert. Alle Endpunkte nehmen JSON über HTTPS entgegen und geben JSON zurück. Antworten werden mit Brotli oder gzip komprimiert, wenn Ihr Client den Header Accept-Encoding sendet.

Basis-URL
https://api.thebeautyapi.com/v1

Die API beschreibt ihre eigenen Endpunkte. Eine Anfrage an die Stammadresse oder /v1 liefert ein Übersichtsdokument mit Methode, URL und Kurzbeschreibung jedes Endpunkts sowie Links zu dieser Dokumentation und zur englischsprachigen OpenAPI-3.1-Spezifikation, die unter /openapi.json bereitsteht. Beide Dokumente sind ohne API-Schlüssel zugänglich. Agenten und SDK-Generatoren benötigen daher nur die Basis-URL als Ausgangspunkt.

API-Übersichtcurl
curl https://api.thebeautyapi.com/              # endpoints, docs_url, openapi_url, authentication
curl https://api.thebeautyapi.com/openapi.json  # OpenAPI 3.1 document

Die englische Fassung dieser Referenz ist auch als einzelne Markdown-Datei mit einem Index für Agenten verfügbar. Entwicklungsagenten können sie mit einer einzigen Anfrage lesen, ohne diese HTML-Seite auswerten zu müssen.

Authentifizierung

Jede Anfrage unter /v1 benötigt einen API-Schlüssel im Header x-api-key. Sie verwalten Ihre Schlüssel im Dashboard: Pro Konto sind bis zu 2 aktive Schlüssel möglich, die Sie jederzeit erstellen, anzeigen und widerrufen können. Ein fehlender, ungültiger oder widerrufener Schlüssel führt zu 403. Nur /health, das Übersichtsdokument und /openapi.json sind öffentlich zugänglich.

Authentifizierte Anfragecurl
curl "https://api.thebeautyapi.com/v1/products/search?q=retinol&page=1" \
  -H "x-api-key: YOUR_API_KEY"

Halten Sie Ihre API-Schlüssel geheim. Rufen Sie die API von Ihrem Server aus auf und hinterlegen Sie niemals einen Schlüssel im Code eines Browsers oder einer mobilen App. Jede Person mit Zugriff darauf kann Ihr Kontingent verbrauchen.

Schnellstart

Speichern Sie Ihren Schlüssel in einer Umgebungsvariablen und durchsuchen Sie den Katalog mit der Programmiersprache Ihrer Wahl.

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

Endpunkte

Produkte

Suchen Sie ein Produkt nach Namen, filtern Sie den Katalog nach Merkmalen und rufen Sie anschließend den vollständigen Datensatz mit Inhaltsstoffen ab. Barcode- und Stapelabfragen liefern denselben vollständigen Datensatz.

GET/v1/products/search

Produkte suchen

Suchen Sie nach Marke und Produktname. Jedes Wort in q muss in der Marke oder im Namen vorkommen, unabhängig von der Reihenfolge. Groß- und Kleinschreibung, Akzente und Satzzeichen werden ignoriert (Dr.Jart+ wird zu dr jart). Das letzte Wort darf unvollständig sein (cera findet CeraVe), sodass eine Autovervollständigung möglich ist. Die Antwort enthält Kurzdatensätze. Über den Produktendpunkt erhalten Sie anschließend den vollständigen Datensatz.

ParameterOrtTypErforderlichBeschreibung
qURLstringJaSuchtext mit 1 bis 200 Zeichen. Verwenden Sie die Marke und den kennzeichnenden Teil des Namens statt des vollständigen Verkaufstitels.
pageURLintegerNeinSeitennummer von 1 bis 51. Optional, Standardwert 1. Jede Seite enthält 20 Ergebnisse.
Anfrage
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OK (erste 2 Ergebnisse angezeigt)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
  }
}
SucheErgebnis
q=CeraVe Moisturizing Cream✓CeraVe Moisturizing Cream und Varianten (Baby, Intensive, Psoriasis, For Dry To Very Dry Skin…).
q=CeraVe Moisturizing Cream Daily Face and Body Moisturizer for Dry Skin✗Kein gespeichertes Produkt entspricht allen Begriffen. no_match.hint nennt das unspezifischste Wort zum Entfernen; no_match.terms zeigt die Trefferzahl je Wort.
q=Laneige sleeping mask✓Alle Nachtmasken von LANEIGE (Water, Lip, Cica, Time Freeze…).

Hinweise:

  1. 01Ein leeres results-Array bedeutet, dass kein Produkt alle gesuchten Wörter enthält. Es bedeutet nicht, dass die Marke fehlt.
  2. 02Wenn total 0 ist, enthält die Antwort no_match: hint nennt das zu entfernende Wort, terms die Trefferzahl je Wort. Entfernen Sie das Wort ohne Treffer (Tippfehler, Positionsnummer auf einem Beleg) oder das unspezifischste Wort (serum, cream, SPF) und versuchen Sie es erneut.
  3. 03Verwenden Sie von Anfang an die Marke und einen kurzen Produktnamen, niemals den vollständigen Titel eines Verkaufseintrags.
  4. 04Jedes Zeichen, das weder Buchstabe noch Ziffer ist, trennt Wörter: Aus Oil-Free werden oil und free, aus 10% wird 10. Nur die ersten 10 Wörter zählen.
  5. 05Eine Suche ohne Buchstaben oder Ziffern liefert 400.
GET/v1/products

Produkte filtern

Finden Sie Produkte nach Kategorie, Marke, Herkunftsland, Formulierungsmerkmalen und Inhaltsstoffen. Alle Filter werden mit AND verknüpft: Jede Bedingung muss erfüllt sein. Die Antwort enthält dieselben Kurzdatensätze wie die Suche.

ParameterOrtTypErforderlichBeschreibung
categoryURLstringNeinExakte Übereinstimmung mit der gespeicherten Kategorie, unter Beachtung der Groß- und Kleinschreibung: skincare, suncare, makeup, haircare, body/bath, fragrance, other, deodorants, oral-care, tools_accessories oder devices. Andere Werte liefern eine leere Seite mit no_match, keinen Fehler.
brandURLstringNeinMarkenname. Groß- und Kleinschreibung, Akzente, Satzzeichen und Leerzeichen werden ignoriert: supergoop findet Supergoop!, sk ii findet SK-II. Tippfehler werden nicht korrigiert. Verwenden Sie die Suche, um den gespeicherten Namen zu finden.
originURLstringNeinExakte Übereinstimmung mit dem gespeicherten Herkunftsland der Marke, unter Beachtung der Groß- und Kleinschreibung, beispielsweise USA, South Korea, France, United Kingdom. Bei ~57% der Produkte ist diese Angabe unbekannt; diese Produkte entsprechen keinem origin-Wert.
fragrance_freeURLbooleanNeinFormulierungsmerkmale. Ebenfalls verfügbar: alcohol_free, paraben_free, sulfate_free, silicone_free.
has_ingredientURLuuidNeinNur Produkte mit diesem Inhaltsstoff. Die IDs erhalten Sie über die Inhaltsstoffendpunkte.
excludes_ingredientURLuuid listNeinProdukte, die keinen dieser Inhaltsstoffe enthalten. Bis zu 10 durch Kommas getrennte IDs.
pageURLintegerNeinSeitennummer von 1 bis 51. Optional, Standardwert 1. Jede Seite enthält 20 Ergebnisse.
Anfrage
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 (erste 2 Ergebnisse angezeigt)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
  }
}

Hinweise:

  1. 01Eine unbekannte oder entfernte Inhaltsstoff-ID liefert in beiden Inhaltsstofffiltern 400. Gespeicherte Aliasse verweisen auf den nach der Dublettenbereinigung beibehaltenen Inhaltsstoff; siehe Inhaltsstoffdaten.
  2. 02Wenn total 0 ist, erklärt no_match.hint, warum kein Produkt den angegebenen Filtern entspricht.
GET/v1/products/{id}

Produkt abrufen

Der vollständige Datensatz: Marke, Kategorie, Herkunft, Formulierungsmerkmale, gehostete Bild-URL und Inhaltsstoffe in der Reihenfolge auf dem Etikett mit den verfügbaren Namen, Funktionen, Bewertungen und chemischen Kennungen.

ParameterOrtTypErforderlichBeschreibung
idPfaduuidJaProdukt-ID.
Anfrage
curl https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23 \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OK (erste 2 Inhaltsstoffeinträge angezeigt)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
    }
  ]
}

Hinweise:

  1. 01Vollständige Datensätze enthalten ingredients_raw auf Produktebene, Produktmetadaten und Inhaltsstoffe als einfache Liste, Abschnitte oder Komponenten. Manche Inhaltsstoffe sind keinem Eintrag im Verzeichnis zugeordnet; dessen Felder sind dann null. Unbekannte Merkmale sind ebenfalls null. Siehe Inhaltsstoffdaten.
  2. 02Aliasse aus der Dublettenbereinigung erhalten frühere IDs: Eine Abfrage über einen Alias liefert das beibehaltene Produkt und dessen ID.
  3. 03concentration wird nur angegeben, wenn der Hersteller sie veröffentlicht. Sie wird niemals geschätzt.
  4. 04Kein Tarif enthält Barcodes in dieser Antwort. Tarife mit Barcode finden Produkte anhand einer GTIN über die Barcode-Suche.
GET/v1/products/barcode/{barcode}

Nach Barcode suchen

Finden Sie ein Produkt anhand eines gescannten Codes oder eines Codes aus Ihrem Katalog (UPC-A, EAN-13, GTIN-8/14). Sie erhalten denselben vollständigen Datensatz wie beim Abruf über die Produkt-ID. Codes für Einzelartikel, Mehrfachpackungen und Varianten (Farbton, Duft, Größe derselben Produktlinie) werden unterstützt. Mit führenden Nullen ergänzte GTIN-Formen desselben Codes (UPC-A, EAN-13, GTIN-14) sind gleichwertig. Nur mit Barcode-Tarifen verfügbar.

ParameterOrtTypErforderlichBeschreibung
barcodePfadstringJa8 bis 14 Ziffern ohne Leerzeichen oder Bindestriche (^[0-9]{8,14}$).
Anfrage
curl https://api.thebeautyapi.com/v1/products/barcode/769915195941 \
  -H "x-api-key: $BEAUTY_API_KEY"
200 OK (erste 2 Inhaltsstoffeinträge angezeigt)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
    }
  ]
}

Hinweise:

  1. 01Die Antwort enthält niemals die Liste der Barcodes eines Produkts. Die API findet ein Produkt anhand eines Codes; sie ermöglicht keine Auflistung der Codes. Die vollständige GTIN-Liste ist ausschließlich in der lizenzierten Datenbank enthalten.
  2. 02403, wenn Ihr Tarif diese Funktion nicht enthält (Meldung: “Your current plan does not include Barcode Lookup access.”). 404 bei fehlendem Treffer. 400 bei ungültigem Format.
  3. 03Zählt als 1 abrechenbarer Aufruf.
  4. 04Rund 61% der Produkte im Katalog haben derzeit einen Code. Die Abdeckung wächst mit weiteren Aktualisierungen.
POST/v1/products/batch

Mehrere Produkte abrufen

Rufen Sie bis zu 50 vollständige Datensätze mit einer Anfrage ab. Das Antwort-Array enthält genauso viele Einträge wie die gesendete ID-Liste und behält deren Reihenfolge bei. Jede unbekannte ID wird durch null dargestellt.

ParameterOrtTypErforderlichBeschreibung
idsAnfragekörperuuid[]Ja1 bis 50 Produkt-IDs.
Anfrage
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 (erste 2 Inhaltsstoffeinträge angezeigt)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
]

Hinweise:

  1. 01Jeder Eintrag, der nicht null ist, verwendet das Format eines vollständigen Produktdatensatzes einschließlich der unter Inhaltsstoffdaten beschriebenen Strukturen und Aliasse.
  2. 02Senden Sie JSON mit Content-Type: application/json. Ein fehlender oder nicht unterstützter Inhaltstyp führt zu 415.
  3. 03Ein ungültiger JSON-Anfragekörper oder ein fehlendes, leeres, mehr als 50 Einträge umfassendes oder Nicht-UUID-Werte enthaltendes ids-Feld führt zu 400.
  4. 04Bei kostenpflichtigen Tarifen wird je Eintrag abgerechnet: 50 IDs zählen als 50 Aufrufe. Der Antwortheader X-Item-Count gibt die abrechenbare Anzahl an.
  5. 05Für die Anfragerate und das Testkontingent von 100 Anfragen zählt ein Stapel als eine Anfrage. Während des Tests entstehen keine Mehrverbrauchskosten.

Endpunkte

Inhaltsstoffe

Durchsuchen Sie das Inhaltsstoffverzeichnis nach INCI-Namen oder Synonymen und rufen Sie den vollständigen Datensatz ab: Funktionen, Bewertungen zu Reizpotenzial und Komedogenität sowie chemische Kennungen. Verwenden Sie die IDs in den Produktfiltern.

GET/v1/ingredients/search

Inhaltsstoffe suchen

Durchsuchen Sie 26.000 Einträge im Inhaltsstoffverzeichnis nach normalisiertem INCI-Namen oder bekanntem Synonym. Verwenden Sie die gefundenen IDs in Produktfiltern oder zum Abruf eines Inhaltsstoffdatensatzes.

ParameterOrtTypErforderlichBeschreibung
qURLstringJaSuchtext mit 1 bis 200 Zeichen.
pageURLintegerNeinSeitennummer von 1 bis 51. Optional, Standardwert 1. Jede Seite enthält 20 Ergebnisse.
Anfrage
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}

Inhaltsstoff abrufen

Der vollständige wissenschaftliche Inhaltsstoffdatensatz: normalisierter Name, Synonyme, Funktionen, Bewertungen zu Reizpotenzial und Komedogenität sowie CAS-, EG-, IUPAC- und Ph.-Eur.-Kennungen.

ParameterOrtTypErforderlichBeschreibung
idPfaduuidJaInhaltsstoff-ID.
Anfrage
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
}

Hinweise:

  1. 01Gespeicherte Aliasse verweisen auf den nach der Dublettenbereinigung beibehaltenen Datensatz. Eine ersatzlos entfernte ID liefert 410, eine unbekannte ID 404.

Endpunkte

Referenz

Dienststatus und allgemeine Funktionen der Endpunkte: Paginierung, Fehler, Tarifgrenzen, Bilder, Barcodes und Versionierung.

GET/health

Dienststatus

Prüft, ob der Dienst antwortet, und nennt Größe und Erstellungsdatum des aktuell über die API verfügbaren Katalogs. built_at (JJJJ-MM-TT, UTC) gibt an, wann diese Version vorbereitet wurde. API-Aktualisierungen erfolgen unabhängig von der herunterladbaren Datenbank; siehe Änderungsverlauf. Wie das Übersichtsdokument unter der Stammadresse und die Spezifikation /openapi.json ist dieser Endpunkt ohne API-Schlüssel zugänglich.

Keine Authentifizierung erforderlich.

Anfrage
curl https://api.thebeautyapi.com/health
200 OKjson
{
  "status": "ok",
  "products": 272761,
  "ingredients": 26420,
  "built_at": "2026-11-09"
}

Paginierung

Endpunkte mit Listen liefern 20 Ergebnisse pro Seite. Senden Sie page (1 bis 51) und lesen Sie das Objekt pagination; fragen Sie weitere Seiten ab, solange has_more true ist. total zählt die Treffer über alle Seiten hinweg. So können Sie einen eindeutigen Treffer von mehreren möglichen Produkten unterscheiden. Für Seiten über 51 gibt die API 400 zurück. Bei mehr als 1.020 Treffern, also 20 × 51, grenzen Sie die Suche mit Filtern ein.

Paginierungsobjektjson
"pagination": { "page": 2, "has_more": true, "total": 47 }

Fehler

Fehler verwenden die üblichen HTTP-Statuscodes und einen einheitlichen JSON-Antwortkörper:

Fehlerantwortjson
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No product with id 00000000-0000-4000-8000-000000000000"
}

Steuern Sie die Fehlerbehandlung anhand von statusCode. Das Feld message erläutert den Fehler und hilft bei der Diagnose. Beispielsweise nennt ein nicht unterstützter Parameter die erlaubten Parameter und den passenden Endpunkt:

Validierungsfehlerjson
{
  "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."
}
StatusBedeutung
400Die Anfrage kann nicht verarbeitet werden: nicht unterstützter Parameter, ungültige ID oder Barcode-Form, unbekannter oder entfernter Inhaltsstoff im Filter, Seite über 51, leerer oder zu langer Suchtext oder ungültige Stapelabfrage. Die Meldung nennt das betroffene Feld und bei unbekannten Parametern die erlaubten Parameter. Korrigieren Sie die Anfrage, bevor Sie sie erneut senden.
402Testzeitraum abgelaufen oder Zahlung erforderlich. Prüfen Sie Ihren Zahlungsstatus im Dashboard, bevor Sie es erneut versuchen.
403API-Schlüssel fehlt, ist ungültig oder deaktiviert, oder die Barcode-Suche ist in Ihrem Tarif nicht enthalten.
404Die Anfrage ist gültig, liefert aber keinen Treffer: kein Produkt oder Inhaltsstoff mit dieser ID, kein Produkt zu diesem Barcode oder eine nicht vorhandene Endpunktadresse. Die Meldung nennt die ID oder den Code.
410Diese Inhaltsstoff-ID wurde ersatzlos entfernt. Suchen Sie nach einem aktuellen Eintrag im Verzeichnis.
413Der Anfragekörper überschreitet 1 MB. Nur der Stapelendpunkt liest einen Anfragekörper. 50 UUIDs benötigen weniger als 3 KB, sodass eine gültige Stapelabfrage diese Grenze nicht erreicht.
415Der Stapelabfrage fehlt der Content-Type-Header oder der Inhaltstyp wird nicht unterstützt. Senden Sie Content-Type: application/json.
429Testkontingent ausgeschöpft (zum Wechsel auf einen kostenpflichtigen Tarif klicken Sie im Dashboard auf „Convert to paid plan“), Anfragerate überschritten oder monatliche Obergrenze erreicht. Bei kostenpflichtigen Tarifen werden Aufrufe über das enthaltene Kontingent hinaus als Mehrverbrauch berechnet. Erst eine höhere Obergrenze, die dem Schutz vor Missbrauch dient, blockiert weitere Aufrufe. Gateway-Obergrenzen werden am 1. des Monats (UTC) zurückgesetzt; kostenpflichtige Kontingente folgen Ihrem Abrechnungsmonat. Das Testkontingent wird nicht zurückgesetzt. Erfolgreiche Testanfragen enthalten X-Trial-Requests-Remaining. Vergrößern Sie bei einer überschrittenen Anfragerate die Abstände zwischen erneuten Versuchen; nutzen Sie bei ausgeschöpftem Testkontingent das Dashboard.
500Interner Fehler auf unserer Seite. Sie können die Anfrage erneut senden.
503Die Zugriffsprüfung ist vorübergehend nicht verfügbar. Versuchen Sie es nach einer Pause erneut und verlängern Sie die Wartezeit zwischen weiteren Versuchen.
504Der API-Server hat nicht rechtzeitig geantwortet. Sie können die Anfrage mit zunehmenden Wartezeiten erneut senden.

Anfrageraten und Kontingente

Neue Konten erhalten sieben Testtage mit insgesamt 100 Anfragen, gemeinsam für alle Schlüssel. Sobald die 100 Anfragen verbraucht sind, liefert die API 429, bis Sie auf einen kostenpflichtigen Tarif umstellen oder der Testzeitraum endet. Während des Tests werden keine Mehrverbrauchskosten berechnet. Die monatliche Grundgebühr wird im Voraus erhoben; Aufrufe über das enthaltene Kontingent hinaus kosten jeweils 0,02 $ und werden am Ende des Abrechnungsmonats berechnet. Bei kostenpflichtigen Tarifen zählt jeder angeforderte Eintrag einer Stapelabfrage als ein Aufruf, während im Testzeitraum der gesamte Stapel als eine Anfrage zählt. Das kostenpflichtige Kontingent wird zu Beginn jedes Abrechnungsmonats zurückgesetzt.

TarifPreisEnthaltene Aufrufe pro MonatAnfragerate
Starter40 $/Monat10.00010 Anfragen/s, kurzzeitig 20
Starter + Barcode60 $/Monat10.00010 Anfragen/s, kurzzeitig 20
Pro200 $/Monat100.00025 Anfragen/s, kurzzeitig 50
Pro + Barcode300 $/Monat100.00025 Anfragen/s, kurzzeitig 50

Anfragen, die die zulässige Anfragerate überschreiten, erhalten 429. Es werden keine Header zur Anfragerate gesendet. Verlängern Sie die Wartezeit zwischen erneuten Versuchen schrittweise (exponentieller Backoff).

Produktdaten

  • Antworten für einzelne Produkte, Stapelabfragen und Barcode-Abfragen enthalten die folgenden Felder. Fehlende Werte sind null.
  • Such- und Filterergebnisse enthalten id, brand, name, category und image_url.
FeldTypBedeutung
product_typestring | nullProduktstruktur, beispielsweise ein Einzelartikel oder ein Set.
subcategorystring | nullGenauere Einordnung innerhalb der Kategorie.
sizestring | nullAngegebene Größe oder Füllmenge mit Einheit oder Beschreibung der Mehrfachpackung.
packagingstring | nullBeschreibung der Verpackung, etwa Flasche, Tube oder Tiegel.
pack_countinteger | nullAnzahl der Artikel in der Packung, sofern bekannt.
shade_namestring | nullFür das Produkt angegebener Farbtonname.
benefitsstring | nullAngegebene Produktvorteile, sofern verfügbar.
directionsstring | nullAnwendungshinweise. Der Text kann Zeilenumbrüche enthalten.
warningsstring | nullWarnhinweise zum Produkt. Der Text kann Zeilenumbrüche enthalten.
ingredients_rawstring | nullInhaltsstofftext aus dem Produkteintrag; siehe die Inhaltsstoffdaten unten.

Inhaltsstoffdaten

Inhaltsstoffdaten liegen in drei Strukturen vor:

  • ingredients: eine einzelne, geordnete Liste.
  • ingredient_sections: benannte Abschnitte mit jeweils einer eigenen Liste.
  • components: die einzelnen Produkte eines Sets, jeweils mit einer Liste oder Abschnitten.
  • Jedes Produkt verwendet genau eine dieser Strukturen; die übrigen Felder werden weggelassen. Eine nicht verfügbare Liste hat den Wert null. Andere vorhandene Listen bleiben zugänglich.

Felder und Werte

  • position: beginnt innerhalb jeder Inhaltsstoffliste, jedes Abschnitts und jeder Komponente bei null.
  • label_name: die Schreibweise des Inhaltsstoffs auf dem Etikett mit Rechtschreibkorrekturen; sie kann vom normalisierten Namen abweichen. concentration: angegebener Prozentwert oder null.
  • Nicht zugeordnete Bezeichnungen behalten ihre Position und ihren Text. id und die Felder des Inhaltsstoffverzeichnisses sind dann null. Zugeordnete Inhaltsstoffe können ein leeres functions-Array haben.
  • Inhaltsstoff-IDs in der API sind UUIDs. Die Werte von ingredient_id in der herunterladbaren Datenbank sind Ganzzahlen.
  • contains_*: true, false oder null (unbekannt). Auch heading in einem Abschnitt und name in einer Komponente können null sein.
  • Erkannte Überschriften werden zu Ingredients, Active ingredients, Inactive ingredients, Medicinal ingredients, Non-medicinal ingredients oder May contain normalisiert. Andere Überschriften behalten ihren Wortlaut.

Inhaltsstofftext

  • ingredients_raw: der Inhaltsstofftext aus dem Produkteintrag, ergänzend zu den strukturierten Listen. Er wird nicht für jeden Abschnitt oder jede Komponente wiederholt.
  • Der ursprüngliche Text und seine Zeilenumbrüche bleiben erhalten, soweit sie vorliegen. Fehlender Text hat den Wert null.

Beispiele für API-Antworten

Inhaltsstofffelder aus beispielhaften API-Antworten. Wählen Sie unten ein Beispiel aus.

Beispiel
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": [
API-Referenz

IDs und Dublettenbereinigung

  • Aliasse aus der Dublettenbereinigung verknüpfen frühere Produkt- und Inhaltsstoff-IDs mit den beibehaltenen Datensätzen.
  • Produktabfragen, einschließlich Stapelabfragen, geben den beibehaltenen Datensatz und dessen ID zurück. Auch Inhaltsstoffabfragen und -filter akzeptieren frühere IDs und verwenden den beibehaltenen Datensatz.
  • Inhaltsstofffilter: Eine unbekannte oder entfernte ID führt für die gesamte Anfrage zu 400.
  • Inhaltsstoffdetails: 410 für eine ersatzlos entfernte ID; 404 für eine unbekannte ID.

Datenbankdateien

  • JSONL: dieselben Inhaltsstoffstrukturen mit numerischen ingredient_id-Verweisen.
  • CSV und SQLite: product_ingredients enthält einfache Listen, product_ingredient_groups enthält Abschnitte und Komponenten und product_group_ingredients deren Einträge.
  • Nicht zugeordnete Bezeichnungen bleiben als Zeile mit einem null-Verweis auf den Inhaltsstoff erhalten.
  • Nullwerte: SQL NULL in SQLite, leere Zellen in CSV-Dateien. In Anführungszeichen gesetzte CSV-Felder erhalten die Zeilenumbrüche im Inhaltsstofftext.

Produktbilder

Das Feld image_url verweist auf ein standardisiertes Produktfoto vor weißem Hintergrund, das über images.thebeautyapi.com bereitgestellt wird. Wir hosten 260.000 Bilder, die Sie direkt in Ihrer Oberfläche anzeigen können, ohne sie herunterzuladen oder selbst zu hosten. Für eine kleine Zahl von Produkten liegt kein Foto vor; dort ist image_url null.

Barcodes

Barcodes dienen als Suchschlüssel, nicht als Antwortfeld. Mit einem Barcode-Tarif findet GET /v1/products/barcode/{barcode} das zu einem UPC-A, EAN-13 oder GTIN-8/14 gehörende Produkt und liefert dessen regulären Datensatz. Kein Tarif gibt die Liste der Codes eines Produkts zurück. Einzel-, Stapel-, Such- und Filterabfragen haben mit und ohne Barcode-Zugriff dasselbe Format. Codes für Einzelartikel, Mehrfachpackungen und Varianten (Farbton, Duft oder Größe derselben Produktlinie) werden unterstützt. Ein UPC-A und seine mit einer führenden Null ergänzte EAN-13-Form sind gleichwertig. Rund 61% der Produkte im Katalog haben mindestens einen Code. Wenn Sie die Codes selbst benötigen, enthält die lizenzierte Datenbank eine gtin14-Liste je Produkt.

Versionierung

Die API verwendet den Pfad /v1. Ihre Clients sollten zusätzliche Antwortfelder ignorieren. Produkte können eine einfache Inhaltsstoffliste, Abschnitte oder Komponenten enthalten; Felder können null sein. Der Abschnitt Inhaltsstoffdaten erklärt den Umgang mit diesen Formaten.

Daten- und API-Aktualisierungen finden Sie im Änderungsverlauf.

In Postman ausprobieren

Um die Endpunkte vor der Implementierung auszuprobieren, importieren Sie unsere Postman-Collection, hinterlegen Sie Ihren API-Schlüssel als Variable und senden Sie Anfragen. Die Collection enthält auch einen Ordner mit absichtlich ungültigen Anfragen, an denen Sie die Antworten 400, 403 und 404 sehen können.

Anleitung lesen: The Beauty API in Postman testen

Starten Sie Ihre Integration

Starten Sie mit sieben Testtagen und 100 Anfragen. Kostenpflichtige Tarife beginnen bei 40 $/Monat mit 10.000 enthaltenen Aufrufen.