GET /v1/alerts/reformulations — Formula Change Alerts

This endpoint returns a list of detected formula changes across products tracked by the Black Hair API. When the API detects that a product’s ingredient list has changed, it creates a reformulation alert capturing the before and after ingredient snapshots, a human-readable diff summary, and a severity rating. You can filter alerts by severity, date range, and brand to build change-monitoring dashboards or notify your users in real time.

Reformulation alerts are available on Growth plans and above. Requests made with a Starter key return a 403 error. See Plans and Limits to upgrade your plan.

Endpoint

GET https://api.blackhairapi.com/v1/alerts/reformulations

Request headers

Header	Value	Required
`X-API-Key`	`bha_...`	Yes

Query parameters

severity

string

Filter alerts by the severity of the formula change. Accepted values: minor, significant, major. When omitted, alerts of all severities are returned.

since

string

Return only alerts detected on or after this timestamp. Must be a valid ISO 8601 datetime string. Example: 2024-01-01T00:00:00Z.

page

integer

The page number to retrieve. Defaults to 1. Must be 1 or greater.

limit

integer

The number of alerts to return per page. Defaults to 20. Accepts values between 1 and 100.

Response

The response object contains a data array of alert objects ordered by detection date, most recent first.

data

array of objects

A list of reformulation alerts ordered by detected_at descending (most recent first). Each item contains the following fields.

Show Alert object

string

The unique UUID of this reformulation alert.

product_id

string

The UUID of the product whose formula changed.

product_name

string

The name of the affected product, included for convenience so you don’t need a separate product lookup.

detected_at

string

The ISO 8601 datetime at which the formula change was detected by the API’s monitoring service.

severity

string

The severity of the detected change. One of: minor (e.g. a preservative swap), significant (e.g. removal of a key active), or major (e.g. addition of a commonly avoided ingredient such as a sulphate or silicone).

diff_summary

string

A plain-English summary of what changed between the old and new formulas, generated by comparing the before and after ingredient lists.

ingredients_before

string

The full raw ingredient list as it appeared before the reformulation was detected.

ingredients_after

string

The full raw ingredient list as it appears after the reformulation was detected.

Example

Fetch major reformulation alerts since January 2024

curl -X GET \
  "https://api.blackhairapi.com/v1/alerts/reformulations?severity=major&since=2024-01-01T00:00:00Z&page=1&limit=20" \
  -H "X-API-Key: bha_your_key_here"

Response

{
  "data": [
    {
      "id": "f7a8b9c0-d1e2-3456-fabc-def012345678",
      "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "product_name": "Moisture Retention Shampoo",
      "detected_at": "2024-03-15T09:42:11Z",
      "severity": "major",
      "diff_summary": "Sodium lauryl sulphate (SLS) added as second ingredient; cocamidopropyl betaine removed. Product is no longer sulphate-free.",
      "ingredients_before": "Aqua, Cocamidopropyl Betaine, Glycerin, Aloe Barbadensis Leaf Juice, Butyrospermum Parkii (Shea) Butter, Panthenol, Citric Acid, Sodium Benzoate, Potassium Sorbate.",
      "ingredients_after": "Aqua, Sodium Lauryl Sulphate, Glycerin, Cocamidopropyl Betaine, Aloe Barbadensis Leaf Juice, Butyrospermum Parkii (Shea) Butter, Panthenol, Citric Acid, Sodium Benzoate, Potassium Sorbate."
    }
  ]
}

Error responses

Status	Meaning
`400`	The `since` parameter was not a valid ISO 8601 datetime string.
`401`	Missing or invalid `X-API-Key` header.
`403`	Your API key is on a plan that does not include reformulation alerts (requires Growth or above).
`429`	You have exceeded your plan’s monthly request limit.

Use the since parameter in combination with a scheduled job to poll for new alerts on a regular cadence — for example, checking every 24 hours for any reformulations detected since your last poll timestamp.

​Endpoint

​Request headers

​Query parameters

​Response

​Example

​Fetch major reformulation alerts since January 2024

​Response

​Error responses

Endpoint

Request headers

Query parameters

Response

Example

Fetch major reformulation alerts since January 2024

Response

Error responses