# Beniz.ai | Universal Agentic Commerce Engine — Full Documentation

Beniz.ai is a multi-tenant AI commerce infrastructure platform. We enrich, optimize, and syndicate retail product catalogs for consumption by AI agents, shopping assistants, and answer engines.

## Architecture Overview
- **Multi-Vector Retrieval Engine:** Products are indexed with 4 semantic vectors per item:
  - `core_product` — General product identity and description
  - `use_case` — Usage scenarios and target personas
  - `feature` — Technical specs, materials, and attributes
  - `q_and_a` — Common questions and conversational intents
- **Intent-Routed Search:** Queries are automatically classified by intent (core_product, use_case, feature, q_and_a) and routed to the optimal vector index.
- **Channel Signal Profiles:** Per-channel optimization for ChatGPT, Gemini, Claude, Perplexity, Google SGE.

## API Endpoints
- `GET /api/agent/semantic-search?q={query}&store_id={id}` — Intent-routed multi-vector semantic search
- `GET /api/agent/search?q={query}&store_id={id}` — Standard product search
- `GET /api/agent/product/{product_id}?store_id={id}` — Full product detail with AI enrichments
- `GET /api/agent/compare?product_ids={id1,id2}&store_id={id}` — Side-by-side product comparison
- `GET /api/agent/best?use_case={text}&store_id={id}` — Best product for a given use case
- `GET /api/agent/attributes/{product_id}?store_id={id}` — Structured product attributes
- `GET /api/agent/readiness?store_id={id}` — AI agent readiness score
- `GET /api/agent/catalog/stats?store_id={id}` — Catalog statistics
- `GET /api/agent/embeddings?product_ids={ids}&store_id={id}` — Raw multi-vector embeddings

## MCP Server (Model Context Protocol)
- **Transport:** SSE at `https://beniz.ai/api/mcp/sse`
- **JSON-RPC:** `https://beniz.ai/api/mcp/jsonrpc`
- **Authentication:** `X-Agent-Key` header
- **Tools:** search_products, semantic_search, compare_products, find_best_product, get_product_attributes, get_catalog_stats, get_agent_readiness, get_product_embeddings

## Feed Formats
For each brand, the following feed formats are available:
- `/feeds/products/{brand_id}.json` — Generic JSON with enriched data
- `/feeds/products/{brand_id}.jsonld` — Schema.org JSON-LD structured data with potentialAction SearchAction
- `/feeds/products/{brand_id}.xml` — Atom XML feed
- `/feeds/google/{brand_id}.xml` — Google Merchant Center RSS XML
- `/feeds/meta/{brand_id}.xml` — Meta Commerce Manager feed
- `/feeds/openai/{brand_id}.json` — OpenAI Commerce optimized feed
- `/feeds/ai-products/{brand_id}.json` — AI reasoning feed with use_cases, pros, cons, Q&A

## Product Schema Fields
Each product in the AI feeds includes:
- `name`, `enriched_name` — Product title (AI-optimized)
- `description`, `long_description`, `detailed_description` — Multi-length descriptions
- `ai_snippet` — Concise AI-ready summary
- `features` — Array of product features
- `consumer_attributes` — Material, fit, style, occasion
- `intent_qna` — Questions and answers for conversational AI
- `ai_suitability` — Reasoning text explaining product relevance
- `discovery_score` — AI readiness score (0-100)
- `channel_readiness` — Per-channel optimization scores
- `seo_tags`, `occasion_tags`, `seasonality_tags` — Discovery metadata

## Discovery Manifests
- `https://beniz.ai/.well-known/ai-plugin.json` — OpenAI ChatGPT plugin discovery
- `https://beniz.ai/.well-known/mcp-config.json` — MCP server discovery for Claude/agents
- `https://beniz.ai/.well-known/ai-catalog.json` — Platform-wide catalog index
- `https://beniz.ai/feeds/brands.json` — Brand directory with product counts
- `https://beniz.ai/sitemap.xml` — XML sitemap with all feeds and pages
- `https://beniz.ai/robots.txt` — Bot permissions for all major AI crawlers

## Partner Brand Catalogs

### Lulu_test
- **Vertical:** apparel
- **Website:** www.lululemon.com
- **Products:** 0
- **Feed:** [https://beniz.ai/feeds/products/lulu-test.json](https://beniz.ai/feeds/products/lulu-test.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/lulu-test.jsonld](https://beniz.ai/feeds/products/lulu-test.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/lulu-test.json](https://beniz.ai/feeds/ai-products/lulu-test.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### Lululemon
- **Vertical:** apparel
- **Website:** www.lululemon.com
- **Products:** 64
- **Feed:** [https://beniz.ai/feeds/products/lululemon.json](https://beniz.ai/feeds/products/lululemon.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/lululemon.jsonld](https://beniz.ai/feeds/products/lululemon.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/lululemon.json](https://beniz.ai/feeds/ai-products/lululemon.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### Melin
- **Vertical:** apparel
- **Website:** www.melin.com
- **Products:** 397
- **Feed:** [https://beniz.ai/feeds/products/melin.json](https://beniz.ai/feeds/products/melin.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/melin.jsonld](https://beniz.ai/feeds/products/melin.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/melin.json](https://beniz.ai/feeds/ai-products/melin.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### Nike_test
- **Vertical:** shoes
- **Website:** www.nike.com
- **Products:** 75
- **Feed:** [https://beniz.ai/feeds/products/nike-test.json](https://beniz.ai/feeds/products/nike-test.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/nike-test.jsonld](https://beniz.ai/feeds/products/nike-test.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/nike-test.json](https://beniz.ai/feeds/ai-products/nike-test.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### StockX
- **Vertical:** shoes
- **Website:** www.stockx.com
- **Products:** 22
- **Feed:** [https://beniz.ai/feeds/products/stockx.json](https://beniz.ai/feeds/products/stockx.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/stockx.jsonld](https://beniz.ai/feeds/products/stockx.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/stockx.json](https://beniz.ai/feeds/ai-products/stockx.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### ajs_wix_store
- **Vertical:** apparel
- **Website:** https://asbjohn.wixstudio.com/my-site-2
- **Products:** 12
- **Feed:** [https://beniz.ai/feeds/products/ajs-wix-store.json](https://beniz.ai/feeds/products/ajs-wix-store.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/ajs-wix-store.jsonld](https://beniz.ai/feeds/products/ajs-wix-store.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/ajs-wix-store.json](https://beniz.ai/feeds/ai-products/ajs-wix-store.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### fjallraven_store
- **Vertical:** sports
- **Website:** https://www.fjallraven.com/us/en-us/
- **Products:** 32
- **Feed:** [https://beniz.ai/feeds/products/fjallraven-store.json](https://beniz.ai/feeds/products/fjallraven-store.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/fjallraven-store.jsonld](https://beniz.ai/feeds/products/fjallraven-store.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/fjallraven-store.json](https://beniz.ai/feeds/ai-products/fjallraven-store.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

### pacsun
- **Vertical:** apparel
- **Website:** www.pacsun.com
- **Products:** 17
- **Feed:** [https://beniz.ai/feeds/products/pacsun.json](https://beniz.ai/feeds/products/pacsun.json)
- **JSON-LD:** [https://beniz.ai/feeds/products/pacsun.jsonld](https://beniz.ai/feeds/products/pacsun.jsonld)
- **AI Products:** [https://beniz.ai/feeds/ai-products/pacsun.json](https://beniz.ai/feeds/ai-products/pacsun.json)
- **Search:** `https://beniz.ai/api/agent/semantic-search?store_id={store_id}&q={query}`

## Contact
- **Platform:** Beniz.ai
- **Support:** support@beniz.ai