managing-bloomreach

name	managing-bloomreach
description	Use when working with Bloomreach — bloomreach commerce search and merchandising platform management including catalog feeds, search configuration, autosuggest, category pages, SEO, A/B testing, pixel tracking, and recommendation widgets. Covers search relevance, catalog health, widget performance, and content personalization metrics.
connection_type	bloomreach
preload	false

Bloomreach Management Skill

Monitor and manage Bloomreach commerce experience and search platform.

MANDATORY: Discovery-First Pattern

Always discover account configuration and catalogs before querying search or analytics.

Phase 1: Discovery

#!/bin/bash
BR_API="https://api.connect.bloomreach.com/dataconnect/api/v1"
BR_SEARCH="https://core.dxpapi.com/api/v1/core"
AUTH="Authorization: Bearer ${BLOOMREACH_API_KEY}"
ACCT="${BLOOMREACH_ACCOUNT_ID}"
DOMAIN="${BLOOMREACH_DOMAIN_KEY}"

echo "=== Account Configuration ==="
curl -s -H "$AUTH" "$BR_API/accounts/$ACCT" | \
  jq -r '"Account: \(.account_id)\nDomain: \(.domain_key)\nStatus: \(.status)"' 2>/dev/null || echo "Check via Bloomreach Dashboard"

echo ""
echo "=== Catalog Status ==="
curl -s -H "$AUTH" "$BR_API/accounts/$ACCT/catalogs" | \
  jq -r '.[] | "\(.catalog_name) | Products: \(.product_count) | Last Feed: \(.last_feed_time) | Status: \(.status)"' 2>/dev/null || echo "Check catalog feeds via dashboard"

echo ""
echo "=== Search Health Check ==="
curl -s "$BR_SEARCH/?account_id=$ACCT&auth_key=${BLOOMREACH_AUTH_KEY}&domain_key=$DOMAIN&request_type=search&search_type=keyword&q=test&rows=1&fl=pid,title" | \
  jq -r '"Search API: \(if .response then "OK (\(.response.numFound) results)" else "Error" end)"'

echo ""
echo "=== Autosuggest Health ==="
curl -s "$BR_SEARCH/?account_id=$ACCT&auth_key=${BLOOMREACH_AUTH_KEY}&domain_key=$DOMAIN&request_type=suggest&q=sh&rows=5" | \
  jq -r '"Autosuggest: \(if .response or .suggestionGroups then "OK" else "Error" end)"'

echo ""
echo "=== Widgets ==="
curl -s -H "$AUTH" "$BR_API/accounts/$ACCT/widgets" | \
  jq -r '.[] | "\(.widget_id) | Type: \(.type) | Active: \(.active)"' 2>/dev/null || echo "Check widgets via dashboard"

Phase 1 outputs: Account config, catalog status, search health, widgets

Phase 2: Analysis

#!/bin/bash
echo "=== Search Performance ==="
curl -s "$BR_SEARCH/?account_id=$ACCT&auth_key=${BLOOMREACH_AUTH_KEY}&domain_key=$DOMAIN&request_type=search&search_type=keyword&q=shoes&rows=5&fl=pid,title,price,thumb_image&stats.field=price" | \
  jq -r '"Results: \(.response.numFound)\nFacets: \(.facet_counts.facet_fields | keys | length)\nPrice Range: \(.stats.stats_fields.price.min // "N/A") - \(.stats.stats_fields.price.max // "N/A")"'

echo ""
echo "=== Category Browse ==="
curl -s "$BR_SEARCH/?account_id=$ACCT&auth_key=${BLOOMREACH_AUTH_KEY}&domain_key=$DOMAIN&request_type=search&search_type=category&q=&rows=1" | \
  jq -r '"Category Browse: \(if .response then "OK (\(.response.numFound) items)" else "Error" end)"'

echo ""
echo "=== Feed History ==="
curl -s -H "$AUTH" "$BR_API/accounts/$ACCT/catalogs/${BLOOMREACH_CATALOG}/feeds" | \
  jq -r '.[:5] | .[] | "\(.feed_id) | Status: \(.status) | Products: \(.product_count) | \(.completed_at)"' 2>/dev/null || echo "Check feed history via dashboard"

echo ""
echo "=== Ranking Rules ==="
curl -s -H "$AUTH" "$BR_API/accounts/$ACCT/ranking-rules" | \
  jq -r '.[] | "\(.name) | Type: \(.type) | Active: \(.active)"' 2>/dev/null ||  

 
 
curl -s -o /dev/null -w  \
  

Output Format

BLOOMREACH STATUS
=================
Account: {account_id} ({domain})
Catalog: {products} products | Last Feed: {time} ({status})
Search API: {status}
Autosuggest: {status}
Widgets: {active}/{total}
Ranking Rules: {count}
Pixel Tracking: {status}
Issues: {list_of_warnings}

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• auth_key vs API key: Search uses auth_key parameter; management uses Bearer token
• Domain key: Multi-site setups require correct domain_key per site
• Catalog feeds: JSON feed format is strict — validate before submission
• Pixel tracking: Required for analytics and personalization — verify implementation
• SDK version: Bloomreach has Discovery (search) and Engagement (CDP) — different APIs