Довідник API

Документація API інгредієнтів косметики

Повний довідник API для endpoint'ів аналізу INCI, оцінювання безпечності, виявлення алергенів і сумісності зі шкірою.

Автентифікація Cosmetics API

Усі запити до INCI API вимагають API-ключ, що передається в заголовку X-API-Key. Отримайте безкоштовний API-ключ у Панелі.

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913" \
  -H "X-API-Key: sk_live_your_api_key"

Застереження щодо даних

Important Disclaimer

The ingredient safety data, scores, and ratings provided by INCI API are for informational and educational purposes only. This information is compiled from public databases and scientific literature, and may contain errors, omissions, or outdated information. INCI API does not guarantee the accuracy, completeness, or reliability of any data presented.

This service does not provide medical, dermatological, or health advice. Safety scores and ratings are algorithmic assessments based on available data and should not be used as a substitute for professional medical advice, diagnosis, or treatment. Always consult a qualified healthcare professional or dermatologist before making decisions about cosmetic products, especially regarding pregnancy safety, allergies, or skin conditions.

INCI API assumes no liability for any decisions made based on the information provided.

Усі відповіді API містять дані про інгредієнти, зібрані з відкритих джерел, як-от EU CosIng, звіти CIR та опублікована наукова література. Точність не гарантується. Оцінки безпечності — алгоритмічні оцінки на основі доступних даних, а не клінічні висновки. Користувачі мають самостійно перевіряти всю інформацію про інгредієнти. Див. наші Умови використання та Ліцензійну угоду API для повних умов.

Endpoint'и API аналізу INCI

GET/v1/products/:barcodeFree+

Пошук косметичного продукту за штрихкодом. Повертає інформацію про продукт, бренд, список INCI та зображення.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "barcode": "3337875597913",
    "name": "La Roche-Posay Toleriane Double Repair",
    "brand": "La Roche-Posay",
    "category": ["Skincare", "Moisturizer"],
    "imageUrls": ["https://cdn.inciapi.com/..."],
    "inciList": [
      "Aqua", "Glycerin", "Dimethicone",
      "Niacinamide", "Ceramide NP"
    ],
    "vertical": "cosmetics",
    "qualityScore": 92
  }
}

GET/v1/products/:barcode/safetyStarter+

Отримайте повний аналіз безпечності продукту. Включає загальний бал та оцінки за кожним інгредієнтом.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/safety" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "overallSafetyScore": 92,
    "cleanBeautyScore": 88,
    "ingredients": [
      {
        "inciName": "Aqua",
        "safetyRating": 1,
        "functions": ["Solvent"],
        "isAllergen": false,
        "isPregnancySafe": true
      },
      {
        "inciName": "Niacinamide",
        "safetyRating": 1,
        "functions": ["Antioxidant", "Brightening"],
        "isAllergen": false,
        "isPregnancySafe": true
      },
      {
        "inciName": "Phenoxyethanol",
        "safetyRating": 4,
        "functions": ["Preservative"],
        "isAllergen": false,
        "isPregnancySafe": true
      }
    ]
  }
}

GET/v1/products/:barcode/allergensStarter+

Отримайте попередження про алергени для продукту. Перевіряє 80 обов'язкових алергенів ЄС, контактні сенсибілізатори та алергени-консерванти.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/allergens" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "allergenWarnings": [
      {
        "inciName": "Linalool",
        "allergenType": "EU Fragrance Allergen",
        "severity": "moderate",
        "description": "Common fragrance allergen, mandatory labeling in EU"
      },
      {
        "inciName": "Citronellol",
        "allergenType": "EU Fragrance Allergen",
        "severity": "low",
        "description": "Fragrance component, potential sensitizer"
      }
    ],
    "totalAllergens": 2,
    "hasEuAllergens": true,
    "hasContactSensitizers": false
  }
}

GET/v1/products/:barcode/compatibility?skinType=sensitiveНевдовзі+

Перевірте сумісність із типом шкіри. Підтримувані типи: жирна, суха, чутлива, комбінована, схильна до акне, нормальна.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/compatibility?skinType=sensitive" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "skinType": "sensitive",
    "compatible": true,
    "score": 95,
    "concerns": [],
    "recommendations": [
      "Product is fragrance-free",
      "Contains ceramides (skin barrier support)",
      "Contains niacinamide (anti-inflammatory)"
    ],
    "allSkinTypes": [
      { "skinType": "sensitive", "compatible": true, "score": 95 },
      { "skinType": "dry", "compatible": true, "score": 90 },
      { "skinType": "oily", "compatible": true, "score": 82 },
      { "skinType": "combination", "compatible": true, "score": 88 },
      { "skinType": "acne-prone", "compatible": true, "score": 78 },
      { "skinType": "normal", "compatible": true, "score": 96 }
    ]
  }
}

GET/v1/products/:barcode/pregnancyНевдовзі+

Перевірте безпечність при вагітності. Позначає ретиноїди, саліцилову кислоту (BHA), гідрохінон та інші небезпечні інгредієнти.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/pregnancy" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "pregnancySafe": true,
    "warnings": [],
    "flaggedIngredients": [],
    "safeAlternatives": [],
    "note": "No pregnancy-unsafe ingredients detected"
  }
}

POST/v1/analyzeНевдовзі+

Аналіз сирого списку INCI без штрихкоду. Надішліть назви інгредієнтів і отримайте повний аналіз безпечності.

Запит

bash

curl -X POST "https://api.inciapi.com/v1/analyze" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inci": [
      "Aqua", "Glycerin", "Niacinamide",
      "Cetearyl Alcohol", "Phenoxyethanol",
      "Retinol", "Linalool"
    ]
  }'

Відповідь

json

{
  "success": true,
  "data": {
    "overallSafetyScore": 78,
    "cleanBeautyScore": 72,
    "ingredients": [
      { "inciName": "Aqua", "safetyRating": 1, "isAllergen": false, "isPregnancySafe": true },
      { "inciName": "Glycerin", "safetyRating": 1, "isAllergen": false, "isPregnancySafe": true },
      { "inciName": "Niacinamide", "safetyRating": 1, "isAllergen": false, "isPregnancySafe": true },
      { "inciName": "Retinol", "safetyRating": 7, "isAllergen": false, "isPregnancySafe": false },
      { "inciName": "Linalool", "safetyRating": 5, "isAllergen": true, "isPregnancySafe": true }
    ],
    "allergenWarnings": [
      { "inciName": "Linalool", "allergenType": "EU Fragrance Allergen", "severity": "moderate" }
    ],
    "pregnancySafe": false,
    "pregnancyWarnings": ["Retinol: Vitamin A derivative, avoid during pregnancy"]
  }
}

GET/v1/ingredients/:inciNameFree+

Отримайте детальну інформацію про конкретний інгредієнт за його назвою INCI.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/ingredients/Niacinamide" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "inciName": "Niacinamide",
    "commonName": "Vitamin B3",
    "casNumber": "98-92-0",
    "safetyRating": 1,
    "functions": ["Antioxidant", "Brightening", "Anti-inflammatory"],
    "isAllergen": false,
    "isPregnancySafe": true,
    "comedogenicity": 0,
    "suitableSkinTypes": ["oily", "dry", "sensitive", "combination", "acne-prone", "normal"],
    "euStatus": "approved",
    "description": "Well-researched skincare ingredient. Helps with hyperpigmentation, fine lines, and skin barrier function."
  }
}

GET/v1/ingredients/search?q=retinolFree+

Пошук інгредієнтів за назвою або функцією. Повертає відповідні інгредієнти з даними безпечності.

Запит

bash

curl -X GET "https://api.inciapi.com/v1/ingredients/search?q=retinol&limit=5" \
  -H "X-API-Key: sk_live_your_api_key"

Відповідь

json

{
  "success": true,
  "data": {
    "ingredients": [
      {
        "inciName": "Retinol",
        "safetyRating": 7,
        "functions": ["Anti-Aging", "Cell Turnover"],
        "isAllergen": false,
        "isPregnancySafe": false
      },
      {
        "inciName": "Retinyl Palmitate",
        "safetyRating": 5,
        "functions": ["Anti-Aging", "Antioxidant"],
        "isAllergen": false,
        "isPregnancySafe": false
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 5
  }
}

POST/v1/products/submitFree+

Надішліть відсутній б'юті-продукт із його списком INCI. Внесені продукти стають доступними після модерації.

Запит

bash

curl -X POST "https://api.inciapi.com/v1/products/submit" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "1234567890123",
    "name": "My Beauty Serum",
    "brand": "Indie Beauty",
    "inciList": ["Aqua", "Hyaluronic Acid", "Niacinamide"]
  }'

Відповідь

json

{
  "success": true,
  "data": {
    "submissionId": "sub_abc123",
    "status": "pending_review",
    "message": "Product submitted successfully. Will be available after moderation."
  }
}

Ліміти запитів Cosmetics API

Ліміти запитів API аналізу інгредієнтів залежать від рівня вашої передплати. Ліміти повертаються в заголовках відповіді.

Тариф	Ліміт	Скидання
Free	100 запитів/день	Щодня опівночі UTC
Starter	5000 запитів/міс	Щомісяця в дату оплати

Заголовки відповіді:

http

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4831
X-RateLimit-Reset: 1711929600

Коди помилок INCI API

Код	Значення	Дія
`400`	Некоректний запит	Перевірте параметри та формат тіла запиту
`401`	Не авторизовано	Перевірте API-ключ у заголовку X-API-Key
`403`	Заборонено	Endpoint вимагає вищого тарифу
`404`	Не знайдено	Продукта чи інгредієнта немає в нашій базі
`429`	Ліміт запитів перевищено	Зачекайте секунди, вказані в Retry-After, та повторіть
`500`	Внутрішня помилка сервера	Повторіть пізніше; зверніться до підтримки, якщо помилка зберігається

Формат відповіді про помилку:

json

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Product not found for barcode: 1234567890123"
  }
}