CosDNA APIcosdna.com ↗
Access CosDNA product data, ingredient safety ratings, supplier listings, and forum posts via 8 structured API endpoints. Analyze ingredient lists for acne and irritant scores.
What is the CosDNA API?
The CosDNA API exposes 8 endpoints covering cosmetic product search, ingredient analysis, supplier discovery, and community content from CosDNA.com. The get_product_details endpoint returns a full ingredient list for any product with per-ingredient safety, acne, and irritant ratings. The analyze_cosmetics endpoint lets you submit a raw ingredient list and receive the same structured ratings without needing a product ID.
curl -X GET 'https://api.parse.bot/scraper/9bcbfb6c-22be-4d42-9a24-08e297777710/search_products?page=1&query=sunscreen' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace cosdna-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.cosdna_cosmetics_api import CosDNA, ProductSummary, Product, IngredientSummary, Ingredient
cosdna = CosDNA()
# Search for sunscreen products and inspect their ingredients
for product in cosdna.products.search(query="sunscreen", limit=3):
print(product.name, product.product_id, product.link)
# Get full product details including ingredient safety ratings
details = cosdna.products.get(product_id="73c6694771")
print(details.name)
for ing in details.ingredients:
print(ing.name, ing.function, ing.acne, ing.safety)
# Search ingredients and drill into details
for result in cosdna.ingredients.search(query="niacinamide", limit=5):
print(result.name, result.ingredient_id)
# Get full ingredient details with related products
ingredient = cosdna.ingredients.get(ingredient_id="af81356377")
print(ingredient.name, ingredient.description)
for rp in ingredient.related_products:
print(rp.name, rp.product_id)
# Analyze a custom ingredient list
for analyzed in cosdna.cosmetics.analyze(ingredient_list="Water, Glycerin, Niacinamide"):
print(analyzed.name, analyzed.function, analyzed.acne, analyzed.irritant)
# Search suppliers
for supplier in cosdna.suppliers.search(query="Hyaluronic Acid"):
print(supplier.product_name, supplier.company)
# Get latest reviews from homepage
for review in cosdna.reviews.latest(limit=5):
print(review.name, review.link)
# Browse forum posts
for post in cosdna.forumposts.list(board_id="13", limit=10):
print(post.title, post.author)
Full-text search over cosmetic products by name. Returns paginated results with product IDs, names, links, and thumbnails. Each product can be drilled into via get_product_details for its full ingredient list.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| sort | string | Sort order for results. |
| queryrequired | string | Search keyword for products (e.g. 'sunscreen', 'moisturizer'). |
{
"type": "object",
"fields": {
"page": "string, the current page number",
"query": "string, the search query used",
"products": "array of product objects with product_id, name, link, and thumbnail fields"
},
"sample": {
"data": {
"page": "1",
"query": "sunscreen",
"products": [
{
"link": "https://www.cosdna.com/eng/cosmetic_22b3696224.html",
"name": "CeraVe Invisible Dry Touch Fluid Sunscreen SPF50+/PA++++",
"thumbnail": "https://www.cosdna.com/images/cos/s34c1696224.png",
"product_id": "22b3696224"
}
]
},
"status": "success"
}
}About the CosDNA API
Product and Ingredient Data
The search_products endpoint accepts a query string and returns paginated results — each with a product_id, name, link, and thumbnail. Pass that product_id to get_product_details to retrieve the full ingredient list for a product, where each ingredient object includes name, ingredient_id, function, acne, irritant, and safety fields. The product name is pulled from the page title and may carry a suffix such as "Ingredient Analysis".
For ingredient-level research, search_ingredients returns matching ingredient_id values that unlock get_ingredient_details. That endpoint surfaces chemical metadata (Formula, Molecular Weight, Cas No), synonyms, a description, and a list of up to 10 related products — useful for tracing which products use a specific compound.
Ingredient Analysis Without a Product ID
analyze_cosmetics accepts a comma-separated ingredient_list string and returns an analysis array with the same function, acne, irritant, and safety fields used in product details. This endpoint is practical for analyzing products not yet in the CosDNA database or for evaluating custom formulations against the site's rating system.
Suppliers, Reviews, and Forum
search_suppliers returns supplier product listings for a given ingredient query, including product_name, company, description, and link. Community data is available through get_latest_reviews, which returns the most recent user-submitted reviews shown on the CosDNA homepage (each with name and link), and get_forum_posts, which accepts a board_id (for example, 13 for Skincare) and a page parameter, returning paginated post title, link, and author fields.
The CosDNA API is a managed, monitored endpoint for cosdna.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when cosdna.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official cosdna.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Scan a product's ingredient list for acne-triggering compounds using
get_product_detailsacne ratings. - Compare irritant scores across multiple products by querying
search_productsand batchingget_product_detailscalls. - Validate a custom formulation before production by submitting it to
analyze_cosmeticsand reviewing safety fields. - Identify raw material suppliers for a specific ingredient via
search_supplierscompany and description data. - Build an ingredient glossary by retrieving CAS numbers, molecular weights, and synonyms from
get_ingredient_details. - Monitor skincare community sentiment by scraping paginated forum posts with
get_forum_postsand a givenboard_id. - Populate a product recommendation feed using
get_latest_reviewsto surface recently reviewed items.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does CosDNA have an official developer API?+
What rating fields does `get_product_details` return per ingredient, and what do they represent?+
get_product_details returns acne, irritant, and safety as numeric fields on each ingredient object, alongside function and ingredient_id. These values correspond to the ratings CosDNA displays on its ingredient analysis pages. The ingredient_id can be passed to get_ingredient_details for additional chemical metadata on any listed ingredient.Does the forum endpoint return post content or just metadata?+
get_forum_posts returns title, link, and author for each post — it does not return the body text or replies of individual forum threads. The API covers the post listing level with board-level pagination via board_id and page. You can fork the API on Parse and revise it to add an endpoint that fetches individual thread content.Can I retrieve user-written review text, star ratings, or skin-type tags through this API?+
get_latest_reviews returns review name and link fields only — no rating scores, review body text, or user metadata. You can fork the API on Parse and revise it to add an endpoint that retrieves full review details from individual review pages.Is there a limitation on how many related products `get_ingredient_details` returns?+
related_products array in get_ingredient_details returns up to 10 product objects. If you need broader product coverage for a given ingredient, search_products with an ingredient name as the query is a practical alternative, and it supports pagination via the page parameter.