API & AI Access

Search through all published products in the directory with support for taxonomy attributes, vertical filters, and facets.

• q (string) - Text query to search product names or brand names (defaults to *)
• group (string) - Filter by vertical product group slug (e.g. cannabis, coffee, cpg)
• category (string) - Filter by exact product category
• state (string) - Filter by state location code (e.g. CA, CO)
• brand (string) - Filter by exact brand slug
• attr.<taxonomy> (string) - Dynamic taxonomy attribute filter (e.g. attr.strain-type=sativa, attr.effects=relaxed,uplifted). Comma-separated values are OR’d; separate taxonomies are AND’d.
• thc_min / thc_max (float) - Percentage range filter for THC
• cbd_min / cbd_max (float) - Percentage range filter for CBD
• terpenes_total_min / terpenes_total_max (float) - Percentage range filter for total terpenes
• facet (string) - Comma-separated taxonomy attribute slugs to compute facets for (e.g. facet=strain-type,effects)
• page (integer) - Page offset (default: 1)
• per_page (integer) - Results per page, up to 100 (default: 24)

curl "https://directory.brandrai.com/api/v1/search?q=gummies&state=CA&group=cannabis&attr.strain-type=hybrid&thc_min=10"

{
  "query": "gummies",
  "page": 1,
  "per_page": 24,
  "found": 1,
  "hits": [
    {
      "id": "1:15",
      "product_name": "Sour Gummies 100mg",
      "brand": "Acme Co",
      "brand_slug": "acme-co",
      "category": "Edibles",
      "state": "CA",
      "price": 20.0,
      "image_url": "https://cdn.brandrai.com/acme/sour-gummies.jpg",
      "rights_flag": "authorized",
      "image_status": "verified",
      "upc": "850000000000",
      "sku_key": "acme-gummy-100",
      "taxonomy_group_slug": "cannabis",
      "attributes": {
        "strain-type": {
          "name": "Strain Type",
          "group": "cannabis",
          "type": "single_select",
          "terms": [
            { "slug": "hybrid", "name": "Hybrid" }
          ]
        },
        "effects": {
          "name": "Effects",
          "group": "cannabis",
          "type": "multi_select",
          "terms": [
            { "slug": "relaxed", "name": "Relaxed" },
            { "slug": "uplifted", "name": "Uplifted" }
          ]
        },
        "cannabinoids": {
          "name": "Cannabinoids",
          "group": "cannabis",
          "type": "lab_test",
          "values": [
            { "slug": "thc", "name": "THC", "value": 10.0, "unit": "%", "display": "10%" }
          ],
          "coa": { "batch": "B-2291", "tested_at": "2026-07-14", "lab": "Verity Analytics" }
        }
      },
      "attributes_filter": {
        "strain-type": ["hybrid"],
        "effects": ["relaxed", "uplifted"],
        "thc": 10.0
      },
      "updated_at": 1792440000
    }
  ],
  "facets": [
    { "field": "category", "values": [ { "value": "Edibles", "count": 1 } ] },
    { "field": "attributes_filter.strain-type", "values": [ { "value": "hybrid", "count": 1 } ] }
  ]
}

Attributes & Facets: attributes is keyed by taxonomy slug and carries the taxonomy’s name, group and type alongside either terms (selected values, with a path breadcrumb for hierarchies) or values (measurements, with unit and a preformatted display) plus any coa metadata. attributes_filter provides normalized slugs and percentages for fast client filtering; only ratio units (%, mg/g, ppm) normalize, so an absolute reading like mg/serving appears under attributes only.

List all active brand profiles in the directory, sorted alphabetically.

• q (string) - Filter brands matching a name or slug
• state (string) - Filter brands active in a state
• category (string) - Filter brands by product category
• page (integer) - Page offset (default: 1)
• per_page (integer) - Results per page, up to 100 (default: 24)

curl "https://directory.brandrai.com/api/v1/brands?per_page=1"

{
  "page": 1,
  "per_page": 1,
  "total": 9,
  "hits": [
    {
      "slug": "backpack-boyz",
      "name": "Backpack Boyz",
      "sampleImageUrl": "https://cdn.brandrai.com/transform/files/.../main.jpg",
      "states": [],
      "categories": ["Bud/Flower", "Vape Carts", "Raw Pre-Rolls"],
      "productCount": 15,
      "verificationState": "unclaimed",
      "updatedAt": 1784906913
    }
  ]
}

Retrieve details for a single brand profile by its unique URL slug. Returns a 404 error if not found.

• include=products - Include the top 100 products belonging to this brand in the response.

curl "https://directory.brandrai.com/api/v1/brands/backpack-boyz?include=products"

The brand’s own authored content, in its own words — about, what they do, values, team, locations, retailers, prices, press, events and announcements. Published by the brand through the BrandrAI app; drafts and anything held back from the public page never appear here.

• keys (string) - Comma-separated module keys to return, e.g. keys=team,locations
• view=summary - Keys, titles and item counts only, without the content bodies
• audience=ai - Exclude modules the brand withheld from AI answers

curl "https://directory.brandrai.com/api/v1/brands/backpack-boyz/content-modules?view=summary"

{
  "brand": { "slug": "backpack-boyz", "name": "Backpack Boyz" },
  "updated_at": 1774483200,
  "content_modules": [
    { "key": "about", "title": "Who we are", "description": "", "item_count": 0 },
    { "key": "locations", "title": "Where to find us", "description": "", "item_count": 4 }
  ]
}

Retrieve an enumerable, paginated list of product listings belonging to a specific brand with full taxonomy attribute filters.

• q (string) - Search query filtering product names for this brand
• group (string) - Filter by vertical product group slug
• category (string) - Filter products by category
• state (string) - Filter products by state location code (e.g. CA)
• attr.<taxonomy> (string) - Dynamic taxonomy attribute filter (e.g. attr.strain-type=hybrid)
• thc_min / thc_max (float) - Percentage range filter for THC
• cbd_min / cbd_max (float) - Percentage range filter for CBD
• terpenes_total_min / terpenes_total_max (float) - Percentage range filter for total terpenes
• facet (string) - Extra attribute facets to compute (e.g. facet=strain-type,effects)
• page (integer) - Page offset (default: 1)
• per_page (integer) - Results per page, up to 100 (default: 24)

curl "https://directory.brandrai.com/api/v1/brands/backpack-boyz/products?per_page=2&attr.strain-type=hybrid"

{
  "query": "",
  "page": 1,
  "per_page": 2,
  "found": 15,
  "hits": [
    {
      "id": "71:6176",
      "product_name": "Backpack Boyz 3.5g Flower",
      "brand": "Backpack Boyz",
      "brand_slug": "backpack-boyz",
      "category": "Bud/Flower",
      "image_url": "https://cdn.brandrai.com/transform/files/.../main.webp",
      "rights_flag": "authorized",
      "image_status": "verified",
      "taxonomy_group_slug": "cannabis",
      "attributes": {
        "strain-type": {
          "name": "Strain Type",
          "group": "cannabis",
          "type": "single_select",
          "terms": [ { "slug": "hybrid", "name": "Hybrid" } ]
        }
      },
      "attributes_filter": {
        "strain-type": ["hybrid"]
      }
    }
  ],
  "facets": []
}

Look up a single verified product image using identifiers like UPC, brand+SKU, or name fuzzy matching. Returns { match: {...} } on success, or { match: null } with a 404 when no match is found.

• upc (string) - UPC barcode digits
• brand (string) - Brand name
• sku (string) - SKU code
• name (string) - Product name (used for fuzzy matching)
• size (string) - Product size (e.g. 3.5g)
• strain (string) - Strain classification (sativa, indica, hybrid)

curl "https://directory.brandrai.com/api/v1/lookup?brand=BrandrAI%20Inc&name=storage%20jar"

{
  "match": {
    "product_id": "71:6176",
    "brand": "BrandrAI Inc",
    "image_url": "https://cdn.brandrai.com/transform/files/.../brandrai-storage-jar-main.webp",
    "match_method": "fuzzy",
    "confidence": 0.667
  }
}

Prefer an exact upc or brand+sku match when you have one. For name matches, check confidence (0–1) before displaying the result.

• search_products(query, category, state, brand_slug, page, per_page)
• get_brand(slug, include_products)
• get_brand_products(slug, query, category, state, page, per_page)
• list_brands(query, state, category, page, per_page)
• get_brand_content(slug, keys, view)
• lookup_product_image(upc, brand, sku, name, size, strain)

{
  "mcpServers": {
    "brandrai-directory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://directory.brandrai.com/mcp"
      ]
    }
  }
}

1 · Replace a wrong or missing image on your menu

The fastest win. You already know the product (UPC, or brand + name) — fetch the brand-approved image and drop it in.

// Given a UPC on your menu, swap in the verified image
const res = await fetch(
  "https://directory.brandrai.com/api/v1/lookup?upc=" + encodeURIComponent(upc)
);
if (res.ok) {
  const { match } = await res.json();
  if (match) imgEl.src = match.image_url;   // brand-approved image
}

2 · Mirror a full catalog

The directory is paginated (100 max per page). Page through /brands, then pull each brand’s products.

async function allBrands() {
  const out = [];
  for (let page = 1; ; page++) {
    const url = "https://directory.brandrai.com/api/v1/brands?per_page=100&page=" + page;
    const { hits } = await (await fetch(url)).json();
    if (!hits.length) break;
    out.push(...hits);
  }
  return out;
}
// then, per brand:
// GET /api/v1/brands/{slug}?include=products

3 · Embed a product search widget

CORS is open, so you can call the API straight from the browser — no proxy, no key.

const url = "https://directory.brandrai.com/api/v1/search?q=" + encodeURIComponent(term);
const { hits } = await (await fetch(url)).json();
// render hits[].product_name + hits[].image_url
// optional: only show hits where hits[].rights_flag === "authorized"

4 · Give an AI agent live access

Add the MCP config above to Claude Desktop, Cursor, or Windsurf. The agent can then search brands and fetch verified images conversationally — always reading the current, brand-approved data.