{"openapi":"3.1.0","info":{"title":"Beniz.ai Agent API","description":"API for AI shopping agents to search, compare, and discover products from enriched catalogs. Authenticate with X-Agent-Key header.","version":"1.0.0","contact":{"name":"Beniz.ai","url":"https://beniz.ai"}},"servers":[{"url":"https://content-gen-api-n2if.onrender.com/api/agent","description":"Agent API"}],"security":[{"AgentKeyHeader":[]}],"components":{"securitySchemes":{"AgentKeyHeader":{"type":"apiKey","in":"header","name":"X-Agent-Key","description":"Agent API key obtained from /keys/create"}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"price":{"type":"string"},"image_url":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"seo_tags":{"type":"array","items":{"type":"string"}},"discovery_score":{"type":"number"},"channel_readiness":{"type":"object"},"review_intelligence":{"type":"object","properties":{"review_count":{"type":"integer"},"average_rating":{"type":"number"},"sentiment_score":{"type":"number"},"summary":{"type":"string"},"themes":{"type":"array","items":{"type":"string"}},"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}}}}}},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"search_method":{"type":"string","enum":["semantic","keyword"]}}},"CompareResult":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"comparison_summary":{"type":"string"}}},"ReadinessScore":{"type":"object","properties":{"store_id":{"type":"string"},"overall_score":{"type":"number"},"dimensions":{"type":"object"},"gaps":{"type":"array","items":{"type":"string"}},"recommendations":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/search":{"get":{"operationId":"searchProducts","summary":"Search products by natural language query","description":"Semantic vector search across the enriched product catalog. Returns ranked results with relevance scores. Supports natural language queries like 'casual summer dresses under $50'.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Natural language search query"},{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Max results to return"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category"},{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID (alternative to X-Agent-Key)"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"401":{"description":"Invalid API key"}}}},"/product/{product_id}":{"get":{"operationId":"getProduct","summary":"Get full product details","description":"Returns complete product information including enriched descriptions, features, SEO tags, consumer attributes, and AI readiness scores.","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Product ID"},{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID"}],"responses":{"200":{"description":"Product details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Product not found"}}}},"/compare":{"get":{"operationId":"compareProducts","summary":"Compare multiple products","description":"Side-by-side comparison of products with shared and differentiating attributes. Useful for AI shopping assistants helping users choose between options.","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated product IDs to compare"},{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID"}],"responses":{"200":{"description":"Comparison results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResult"}}}}}}},"/best":{"get":{"operationId":"getBestProducts","summary":"Get best products for a use case","description":"Returns top-ranked products for a specific use case or intent query, optimized for AI recommendation scenarios.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Use case query (e.g. 'gift for mom', 'outdoor running')"},{"name":"limit","in":"query","schema":{"type":"integer","default":5},"description":"Max results"},{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID"}],"responses":{"200":{"description":"Best products for the query"}}}},"/attributes/{product_id}":{"get":{"operationId":"getProductAttributes","summary":"Get structured product attributes","description":"Returns consumer attributes, intent Q&A pairs, competitive anchors, and surface variants for a product.","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Product ID"},{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID"}],"responses":{"200":{"description":"Product attributes and metadata"}}}},"/readiness":{"get":{"operationId":"getReadinessScore","summary":"Get AI readiness score for a store","description":"Comprehensive readiness assessment showing how well the catalog is optimized for each AI shopping platform (ChatGPT, Gemini, Google SGE, Perplexity, Claude).","parameters":[{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID"}],"responses":{"200":{"description":"Readiness score breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessScore"}}}}}}},"/catalog/stats":{"get":{"operationId":"getCatalogStats","summary":"Get catalog statistics","description":"Returns summary statistics for the store's catalog including product counts, enrichment coverage, and syndication status.","parameters":[{"name":"store_id","in":"query","schema":{"type":"string"},"description":"Store UUID"}],"responses":{"200":{"description":"Catalog statistics"}}}}}}