Skip to main content
This endpoint generates personalised product recommendations by combining vector similarity search with GPT-4o-mini ranking. You send a hair profile — curl pattern, porosity level, active concerns, and an optional budget ceiling — and the API returns a ranked list of products drawn from the catalog, each accompanied by a plain-English explanation of why it suits the profile.
The recommendation engine is available on Pro and Enterprise plans only. Requests made with a Starter or Growth key return a 403 error. See Plans and Limits for upgrade options.

​
Endpoint

POST https://api.blackhairapi.com/v1/recommend/

​
Request headers

HeaderValueRequired
X-API-Keybha_...Yes
Content-Typeapplication/jsonYes

​
Request body

​
hair_type
string
required
The curl pattern of the user’s hair, following the Andre Walker typing system. Accepted values include 3a, 3b, 3c, 4a, 4b, and 4c. Example: "4c".
​
porosity
string
required
The hair’s porosity level, which determines how well it absorbs and retains moisture. Accepted values: "low", "medium", "high".
​
concerns
array of strings
A list of the user’s primary hair concerns. Accepted values: dryness, breakage, growth, scalp, frizz, definition, moisture, protein. Example: ["dryness", "breakage", "frizz"]. Defaults to an empty list.
​
budget_max
number
The maximum price the user is willing to spend, in the currency specified by currency. Products with a minimum price above this threshold are excluded from recommendations. Example: 25.00.
​
currency
string
The currency code used to interpret budget_max. Defaults to "GBP". Example: "USD".
​
exclude_ingredients
array of strings
A list of ingredient names that should not appear in recommended products. The filter is applied before AI ranking. Example: ["mineral oil", "dimethicone"].
​
limit
integer
The maximum number of recommendations to return. Defaults to 5. Must be a positive integer.

​
Response

​
query
object
An echo of the hair profile fields used to generate recommendations, for confirmation and caching purposes.
​
recommendations
array of objects
A ranked list of recommended products, sorted by rank (best match first). Each item contains the following fields.

​
Example

curl -X POST \
  "https://api.blackhairapi.com/v1/recommend/" \
  -H "X-API-Key: bha_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "hair_type": "4c",
    "porosity": "high",
    "concerns": ["dryness", "breakage", "frizz"],
    "budget_max": 25.00,
    "currency": "GBP",
    "exclude_ingredients": ["mineral oil", "dimethicone"],
    "limit": 3
  }'

​
Response

{
  "query": {
    "hair_type": "4c",
    "porosity": "high",
    "concerns": ["dryness", "breakage", "frizz"]
  },
  "recommendations": [
    {
      "rank": 1,
      "reason": "This deep conditioner is formulated with shea butter and hydrolysed keratin, making it ideal for high-porosity 4c hair that struggles to retain moisture. The protein-moisture balance directly targets breakage while the slip reduces frizz during detangling.",
      "product": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Intensive Repair Deep Conditioner",
        "brand": "Mielle Organics",
        "category": "deep conditioner",
        "price_range": {"min": 9.99, "max": 12.99},
        "buy_url": "https://www.example.com/products/intensive-repair-deep-conditioner",
        "hair_types": ["4a", "4b", "4c"],
        "sulphate_free": true,
        "silicone_free": true
      }
    },
    {
      "rank": 2,
      "reason": "This leave-in contains glycerin and aloe vera, both excellent humectants for thirsty high-porosity strands. It layers well under a sealant oil and is free from mineral oil and silicones as requested.",
      "product": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Hydrating Leave-In Detangler",
        "brand": "Cantu",
        "category": "leave-in conditioner",
        "price_range": {"min": 6.49, "max": 8.99},
        "buy_url": "https://www.example.com/products/hydrating-leave-in-detangler",
        "hair_types": ["3c", "4a", "4b", "4c"],
        "sulphate_free": true,
        "silicone_free": true
      }
    },
    {
      "rank": 3,
      "reason": "This styling cream provides long-lasting moisture and frizz control for 4c coils without heavy silicones. The shea and mango butter blend helps seal moisture into high-porosity shafts and reduces breakage from styling manipulation.",
      "product": {
        "id": "c3d4e5f6-a7b8-9012-cdef-012345678902",
        "name": "Curl Defining Styling Cream",
        "brand": "As I Am",
        "category": "styling cream",
        "price_range": {"min": 10.00, "max": 14.50},
        "buy_url": "https://www.example.com/products/curl-defining-styling-cream",
        "hair_types": ["3b", "3c", "4a", "4b", "4c"],
        "sulphate_free": true,
        "silicone_free": false
      }
    }
  ]
}

​
Error responses

StatusMeaning
401Missing or invalid X-API-Key header.
403Your API key is on a plan that does not include the recommendation engine (requires Pro or Enterprise).
404No products matched the supplied profile after filtering. Try relaxing your budget_max or exclude_ingredients constraints.
422Request body failed validation — check that hair_type and porosity are present and correctly typed.
429You have exceeded your plan’s monthly request limit.
If you supply a very restrictive combination of budget_max and exclude_ingredients, the API may return a 404 because all candidate products are filtered out before ranking. Broaden your criteria if this happens.