Identify the widget type and widget_id you want to call; widget IDs are configured in the Bloomreach dashboard for each recommendation strategy (e.g., 'recently viewed', 'similar products', 'top sellers').
Send a GET request to the production endpoint: https://pathways.dxpapi.com/api/v2/widgets/{widget_type}/{widget_id}?account_id=YOUR_ACCOUNT&domain_key=YOUR_DOMAIN&_br_uid_2=USER_COOKIE.
Pass the auth-key as a request header (Authorization: YOUR_AUTH_KEY) for the v2 API; unlike v1, the v2 API does not accept the auth key as a query parameter.
Include item_ids (comma-separated product IDs) for item-context widgets like 'similar items' or 'bought together'; include user_id and _br_uid_2 for user-context widgets like 'personalized recommendations'.
Parse the response JSON; results are in the response.docs array. Cache responses per user/product at the edge according to the Bloomreach caching guide to reduce latency and API load.
Known gotchas
Requests must be kept under 16 KB in total size; large item_ids lists (many product IDs) can push requests over this limit.
Omitting domain_key from the request will return a 4xx error — this has been required since March 2023 across all Recommendations and Pathways APIs.
Widget IDs are environment-specific (staging vs. production); use staging endpoint https://pathways-staging.dxpapi.com for development.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp