Skip to main content
This guide walks you through everything you need to make your first successful call to Black Hair API. By the end you will have retrieved a live product listing and looked up the ingredient profile of a specific ingredient — all from your terminal or a script.
1

Get an API key

Visit blackhairapi.com/pricing and subscribe to the plan that fits your use case. Once your payment is confirmed, your API key is emailed to you — check your inbox and spam folder.Your key looks like this:
bha_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8
Keys always begin with the bha_ prefix followed by a URL-safe random string. Store your key in an environment variable or a secrets manager — never hard-code it in your source files.
export BLACK_HAIR_API_KEY="bha_your_api_key_here"
2

Make your first request

Call GET /v1/products/ to retrieve the first page of the product catalog. Pass your API key in the X-API-Key header on every request.
curl https://api.blackhairapi.com/v1/products/ \
  -H "X-API-Key: bha_your_api_key_here"
A successful response returns 200 OK. If you see 401 Unauthorized, double-check that the X-API-Key header is present and that your key begins with bha_.
3

Parse the response

The /v1/products/ endpoint returns a data array of product objects and a meta block with pagination details. Here is a representative response:
{
  "data": [
    {
      "id": "a3f1c2d4-e5b6-7890-abcd-ef1234567890",
      "name": "Curl Activator Cream",
      "brand": {
        "id": "b1e2f3a4-c5d6-7890-abcd-ef0987654321",
        "name": "Mielle Organics",
        "is_black_owned": true
      },
      "category": "styler",
      "description": "A lightweight curl-activating cream that defines and hydrates all curl types without crunch.",
      "price_range": {
        "min": 8.99,
        "max": 12.99
      },
      "regions": ["US", "UK"],
      "images": ["https://cdn.blackhairapi.com/products/curl-activator-cream.jpg"],
      "buy_url": "https://example.com/curl-activator-cream",
      "is_active": true,
      "hair_profile": {
        "hair_types": ["3C", "4A", "4B"],
        "porosity": ["normal", "high"],
        "concerns": ["dryness", "definition"]
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "count": 20
  }
}
Each product includes a nested brand object (with an is_black_owned flag), a hair_profile describing the curl types and porosity levels the product is suited for, and a price_range object with min and max values in USD.To retrieve a specific product and its full ingredient breakdown, call GET /v1/products/{id}?include=ingredients:
curl "https://api.blackhairapi.com/v1/products/a3f1c2d4-e5b6-7890-abcd-ef1234567890?include=ingredients" \
  -H "X-API-Key: bha_your_api_key_here"
4

Try the ingredient lookup

The /v1/ingredients/lookup endpoint lets you look up any ingredient by name and get back its classification, safety flags, and compatibility notes. Try it with a common humectant:
curl "https://api.blackhairapi.com/v1/ingredients/lookup?name=glycerin" \
  -H "X-API-Key: bha_your_api_key_here"
The response includes the ingredient’s function (e.g. humectant), whether it is a sulphate, silicone, or paraben, and its moisture and protein contribution scores — the same data used to power the product-level ingredient flags.
Every plan has both a per-minute and a monthly request limit. The Starter plan allows 5 requests per minute and 100 requests per month. If you exceed either limit, the API returns 429 Too Many Requests. See Plans & Limits for a full breakdown of all tier allowances and upgrade options.