The Black Hair API gives you full-text search and multi-dimensional filtering across the product catalog so you can surface relevant results for any hair profile. Every request must include your X-API-Key header with your bha_ prefixed key.
Basic product search
Use the q parameter to run a case-insensitive keyword search against product names. Results are paginated — see the note below on controlling page size.
curl -G https://api.blackhairapi.com/v1/products/ \
--data-urlencode "q=shea butter" \
-H "X-API-Key: bha_your_api_key"
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Shea Butter Deep Moisture Cream",
"brand": {
"id": "b9e1f2a3-4c5d-6e7f-8090-a1b2c3d4e5f6",
"name": "Mielle Organics",
"is_black_owned": true
},
"category": "conditioner",
"description": "A rich, whipped cream formulated with raw shea butter for intense moisture retention.",
"price_range": { "min": 9.99, "max": 12.99, "currency": "USD" },
"regions": ["US", "UK"],
"images": ["https://cdn.blackhairapi.com/products/shea-cream.jpg"],
"buy_url": "https://www.mielleorganics.com/products/shea-butter-deep-moisture-cream",
"is_active": true,
"hair_profile": {
"hair_types": ["4a", "4b", "4c"],
"porosity": ["high"],
"concerns": ["dryness", "breakage"]
}
}
],
"meta": {
"page": 1,
"limit": 20,
"count": 1
}
}
All list endpoints are paginated. Use the page and limit query parameters to navigate results. page starts at 1 and limit accepts values between 1 and 100 (default 20).
Filter by hair type
Pass a hair_type value to return only products whose hair profile includes that curl pattern. You can filter on a single type or a comma-separated list.
# Single type
curl "https://api.blackhairapi.com/v1/products/?hair_type=4c" \
-H "X-API-Key: bha_your_api_key"
# Multiple types
curl "https://api.blackhairapi.com/v1/products/?hair_type=3b,4a" \
-H "X-API-Key: bha_your_api_key"
{
"data": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
"name": "Moisture Bomb Leave-In Conditioner",
"brand": {
"id": "d5e6f7a8-b9c0-1234-def0-345678901bcd",
"name": "Camille Rose",
"is_black_owned": true
},
"category": "leave-in",
"description": "A lightweight leave-in that seals moisture for tightly coiled textures.",
"price_range": { "min": 11.99, "max": 14.99, "currency": "USD" },
"regions": ["US"],
"images": ["https://cdn.blackhairapi.com/products/moisture-bomb.jpg"],
"buy_url": "https://www.camillerose.com/products/moisture-bomb",
"is_active": true,
"hair_profile": {
"hair_types": ["4b", "4c"],
"porosity": ["high", "medium"],
"concerns": ["dryness", "shrinkage"]
}
}
],
"meta": {
"page": 1,
"limit": 20,
"count": 1
}
}
Exclude harmful ingredients
Use the boolean ingredient flags to filter out products that contain sulphates, silicones, or parabens. Each flag defaults to null (no filter applied). Set any of them to true to exclude products with that ingredient class.
curl "https://api.blackhairapi.com/v1/products/?exclude_sulphates=true&exclude_parabens=true&exclude_silicones=true" \
-H "X-API-Key: bha_your_api_key"
You can combine ingredient exclusions with any other filter. For example, ?hair_type=4c&exclude_sulphates=true&category=shampoo returns sulphate-free shampoos formulated for 4C hair.
Filter by Black-owned brands
Set is_black_owned=true to return only products from brands flagged as Black-owned in the catalog.
curl "https://api.blackhairapi.com/v1/products/?is_black_owned=true" \
-H "X-API-Key: bha_your_api_key"
Get full ingredient data for a product
Fetch a single product by its UUID. By default the response omits the detailed ingredient breakdown. Pass include=ingredients to add it.
curl "https://api.blackhairapi.com/v1/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890?include=ingredients" \
-H "X-API-Key: bha_your_api_key"
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Shea Butter Deep Moisture Cream",
"brand": {
"id": "b9e1f2a3-4c5d-6e7f-8090-a1b2c3d4e5f6",
"name": "Mielle Organics",
"is_black_owned": true
},
"category": "conditioner",
"description": "A rich, whipped cream formulated with raw shea butter for intense moisture retention.",
"price_range": { "min": 9.99, "max": 12.99, "currency": "USD" },
"regions": ["US", "UK"],
"images": ["https://cdn.blackhairapi.com/products/shea-cream.jpg"],
"buy_url": "https://www.mielleorganics.com/products/shea-butter-deep-moisture-cream",
"is_active": true,
"hair_profile": {
"hair_types": ["4a", "4b", "4c"],
"porosity": ["high"],
"concerns": ["dryness", "breakage"]
},
"ingredients": {
"raw_list": "Water, Butyrospermum Parkii (Shea) Butter, Glycerin, Cetearyl Alcohol, Behentrimonium Methosulfate, Panthenol, Aloe Barbadensis Leaf Juice, Fragrance",
"has_sulphates": false,
"has_parabens": false,
"has_silicones": false,
"protein_level": "low",
"moisture_level": "high",
"porosity_match": ["high", "medium"],
"flags": ["shea-butter", "aloe-vera", "glycerin"]
}
}
ingredients object fields are:
The full ingredient list as it appears on the product label.
true if the product contains sulphate surfactants.
true if the product contains paraben preservatives.
true if the product contains silicone compounds.
Assessed protein concentration: low, medium, or high.
Assessed moisture concentration: low, medium, or high.
Porosity types this formula is suited for, e.g. ["high", "medium"].
Notable ingredient tags, e.g. ["shea-butter", "castor-oil", "protein-free"].
Browse brands
The brands endpoint lets you search the brand catalog directly. Filter to Black-owned brands with is_black_owned=true, or search by name with the q parameter.
curl "https://api.blackhairapi.com/v1/brands/?is_black_owned=true" \
-H "X-API-Key: bha_your_api_key"
{
"data": [
{
"id": "b9e1f2a3-4c5d-6e7f-8090-a1b2c3d4e5f6",
"name": "Mielle Organics",
"slug": "mielle-organics",
"origin_country": "US",
"is_black_owned": true,
"website": "https://www.mielleorganics.com",
"product_count": 34
},
{
"id": "d5e6f7a8-b9c0-1234-def0-345678901bcd",
"name": "Camille Rose",
"slug": "camille-rose",
"origin_country": "US",
"is_black_owned": true,
"website": "https://www.camillerose.com",
"product_count": 28
}
]
}
Use the brand id returned here as the brand_id filter parameter on the /v1/alerts/reformulations endpoint to monitor ingredient changes for a specific brand.
