Open Data Access & API

The CleanFormulation Open Data API provides structured, programmatic access to maintained ingredient reference data used across the CleanFormulation research platform. The API is designed for researchers, educators, developers, and journalists who require transparent, machine-readable ingredient identifiers, generated and maintained using the processes described in our Data & Methodology documentation.

What This API Provides Today

Each record represents a normalized ingredient identity used internally across research articles, ingredient pages, and transparency analysis, with source validation described in Evidence & Sources.

  • Ingredient name (INCI or commonly used designation)
  • Stable slug identifier
  • CAS number where publicly established

This API does not currently return safety verdicts, medical guidance, or regulatory compliance decisions.

Base Endpoint

GET /api/vv/ingredients

Returns a list of ingredient records matching a query string. Intended for search, autocomplete, indexing, and reference tooling.

Supported Query Parameters

Parameter Description
query Case-insensitive name search (starts-with prioritized)
cas Exact CAS number lookup

Example Requests

GET /api/vv/ingredients?query=sodium

GET /api/vv/ingredients?cas=151-21-3

Example Response


  [
  {
    "name": "Sodium Lauryl Sulfate",
    "slug": "sodium-lauryl-sulfate",
    "cas": "151-21-3"
  },
  {
    "name": "Sodium Laureth Sulfate",
    "slug": "sodium-laureth-sulfate",
    "cas": "9004-82-4"
  }
]

Canonical Ingredient Endpoint

GET /api/vv/ingredients/{slug}

Returns a single ingredient record using its canonical slug identifier. This endpoint is intended to act as a stable machine-readable reference for citation, indexing, and dataset integration.

Example

GET /api/vv/ingredients/sodium-lauryl-sulfate

Response

{
  "name": "Sodium Lauryl Sulfate",
  "slug": "sodium-lauryl-sulfate",
  "cas": "151-21-3"
}

Planned Endpoints (Not Yet Public)

The following endpoints are under active design and are not currently exposed. They are listed here to document the intended API surface and future compatibility.

Endpoint Planned Purpose Status
/api/vv/soap-brands Soap brand transparency reference dataset Planned
/api/vv/research-updates Structured feed of published research updates and publication log Planned

No guarantees are made regarding release timelines or field definitions for planned endpoints.

Rate Limits & Usage

Public API access is rate-limited to support fair use and platform stability. Requests include standard rate-limit headers indicating remaining quota. 

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1737312000

The API is intended for research, education, and transparency tooling. High-volume automated scraping or resale of the dataset without attribution is prohibited under the terms defined in the Data License.

Data Licensing & Attribution

Public API data is made available under the Creative Commons Attribution 4.0 (CC BY 4.0) license unless otherwise noted. Attribution to CleanFormulation is required when redistributing or publishing derived datasets.

See the Data License and Ethics & Transparency pages for detailed terms.