API 레퍼런스

화장품 성분 API 문서

INCI 분석, 안전성 점수, 알레르기 탐지, 피부 적합성 엔드포인트에 대한 전체 API 레퍼런스입니다.

화장품 API 인증

INCI API에 대한 모든 요청에는 X-API-Key 헤더로 보내는 API 키가 필요합니다. 무료 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 라이선스 계약을 참고하세요.

INCI 분석 API 엔드포인트

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+

제품의 알레르기 경고를 가져옵니다. EU 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."
  }
}

화장품 API 요청 제한

성분 분석 API의 요청 제한은 구독 등급에 따라 달라집니다. 제한값은 응답 헤더로 반환됩니다.

요금제	제한	초기화
Free	하루 100회 요청	매일 자정 UTC
Starter	월 5,000회 요청	매월 청구일

응답 헤더:

http

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

INCI API 오류 코드

코드	의미	조치
`400`	잘못된 요청	요청 매개변수와 본문 형식을 확인하세요
`401`	인증되지 않음	X-API-Key 헤더의 API 키를 확인하세요
`403`	권한 없음	엔드포인트는 상위 요금제가 필요합니다
`404`	찾을 수 없음	제품 또는 성분이 데이터베이스에 없습니다
`429`	요청 한도 초과	Retry-After 초만큼 기다린 후 다시 시도하세요
`500`	서버 내부 오류	잠시 후 다시 시도하고 계속되면 지원팀에 문의하세요

오류 응답 형식:

json

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