{"openapi":"3.1.0","info":{"title":"Curie 3D Product Commerce API","description":"Search and discover products across thousands of Shopify stores with interactive 3D models. Browse by category, brand, or keyword. Products with 3D models can be viewed using GLB and USDZ formats. Requires Curie Pro subscription for full access.","version":"2.0.0","contact":{"name":"Curie Vision","email":"support@curie.co","url":"https://curie.io"}},"servers":[{"url":"https://chat.curie.app","description":"Curie Shopify App (unified catalog + OAuth)"},{"url":"https://curie-api.curievision.workers.dev","description":"Curie Cloudflare Worker API (legacy product endpoints)"}],"security":[{"oauth2":[]}],"paths":{"/api/catalog/search":{"get":{"operationId":"searchCatalog","summary":"Search the unified product catalog across all stores","description":"Search products across all connected Shopify stores. Supports natural language queries, brand filtering, category filtering, and pagination. Returns products with images, prices, 3D model availability, and store information.","security":[{"oauth2":["read:products"]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query. Supports natural language like 'ergonomic office chair' or 'vintage leather bag'","example":"wireless noise-canceling headphones"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":50},"description":"Maximum number of results to return"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number for pagination"},{"name":"brand","in":"query","schema":{"type":"string"},"description":"Filter by brand name","example":"Sony"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by product category","example":"Electronics"},{"name":"has3dModel","in":"query","schema":{"type":"boolean"},"description":"When true, only return products with interactive 3D models"}],"responses":{"200":{"description":"Search results from the unified catalog","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer","description":"Total number of matching products"},"page":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean","description":"Whether more pages of results exist"},"query":{"type":"string","description":"The search query that was executed"}}}}}},"401":{"description":"Authentication required (Curie Pro subscription needed)"}}}},"/api/products":{"get":{"operationId":"searchProducts","summary":"Search products by name, brand, or category","description":"List and filter products from the catalog. Supports text search, brand filtering, pagination, and filtering by 3D model availability. Returns product metadata including images, prices, and 3D model URLs.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query to match against product name, brand, description, or SKU","example":"wireless headphones"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":100},"description":"Maximum number of products to return"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Number of products per page"},{"name":"brand","in":"query","schema":{"type":"string"},"description":"Filter by brand name","example":"Sony"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by product category","example":"Electronics"},{"name":"hasProductionGradeModel","in":"query","schema":{"type":"boolean"},"description":"When true, only return products that have high-quality 3D models available for viewing"}],"responses":{"200":{"description":"List of products matching the query","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer","description":"Total number of matching products"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"hasMore":{"type":"boolean","description":"Whether more pages of results exist"}}}}}}}}},"/api/products/{productId}":{"get":{"operationId":"getProduct","summary":"Get detailed product info including 3D model URLs","description":"Retrieve full details for a single product by ID. Includes all metadata, images, 3D model URLs (GLB and USDZ), pricing, and vendor links.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique product identifier (UUID)"}],"responses":{"200":{"description":"Full product details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Product not found"}}}}}}}}},"/api/products/search":{"get":{"operationId":"searchProductsFull","summary":"Full-text search with relevance scoring","description":"Perform a full-text search across all product fields with relevance-based ranking. More powerful than the basic /api/products query parameter. Use this for natural language product searches.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query. Supports natural language like 'ergonomic standing desk under $500'","example":"wireless noise-canceling headphones"},{"name":"size","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":50},"description":"Number of results to return"}],"responses":{"200":{"description":"Search results ranked by relevance","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"query":{"type":"string","description":"The search query that was executed"}}}}}}}}},"/api/products/{productId}/related":{"get":{"operationId":"getRelatedProducts","summary":"Get products related to a specific product","description":"Find products similar or related to a given product. Uses brand, category, and attribute matching to suggest alternatives and complementary items.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Product ID to find related products for"}],"responses":{"200":{"description":"List of related products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"sourceProductId":{"type":"string"}}}}}},"404":{"description":"Source product not found"}}}},"/api/products/featured":{"get":{"operationId":"getFeaturedProducts","summary":"Get featured products with 3D models","description":"Retrieve a curated list of featured products that have high-quality 3D models and are popular or noteworthy.","responses":{"200":{"description":"List of featured products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}}}},"/api/products/new-arrivals":{"get":{"operationId":"getNewArrivals","summary":"Get newest products added to the catalog","description":"Retrieve the most recently added products, sorted by creation date (newest first).","responses":{"200":{"description":"List of newest products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 authorization code flow. Requires Curie Pro subscription.","flows":{"authorizationCode":{"authorizationUrl":"https://chat.curie.app/api/oauth/authorize","tokenUrl":"https://chat.curie.app/api/oauth/token","scopes":{"read:products":"Search and view products in the catalog"}}}}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string","description":"Unique product identifier (UUID)"},"title":{"type":"string","description":"Product display name"},"productName":{"type":"string","description":"Alternative product name field"},"brand":{"type":"string","description":"Brand name"},"displayPrice":{"type":"string","description":"Formatted price string (e.g. '$180')"},"productCategory":{"type":"string","description":"Product category (e.g. Electronics, Apparel, Home & Garden)"},"gender":{"type":"string","description":"Target gender (e.g. Men, Women, Unisex)"},"sku":{"type":"string","description":"Product SKU / style code"},"genAiDescription":{"type":"string","description":"AI-generated product description"},"imageUrl":{"type":"string","format":"uri","description":"Primary product image URL"},"hasProductionGradeModel":{"type":"boolean","description":"Whether this product has a high-quality 3D model available"},"reconstructionModelGlb":{"type":"string","format":"uri","description":"URL to GLB 3D model file (for web 3D viewers)"},"reconstructionModelUsdz":{"type":"string","format":"uri","description":"URL to USDZ 3D model file (for Apple AR Quick Look)"},"reconstructionUrl":{"type":"string","format":"uri","description":"Alternative GLB model URL"},"reconstructionUrlUsdz":{"type":"string","format":"uri","description":"Alternative USDZ model URL"},"premierVendor":{"type":"object","description":"Primary retailer for this product","properties":{"shop_name":{"type":"string"},"link":{"type":"string","format":"uri"},"price":{"type":"string"}}},"affiliateLinks":{"type":"array","description":"Purchase links from various retailers","items":{"type":"object","properties":{"shop_name":{"type":"string"},"url":{"type":"string","format":"uri"},"price":{"type":"string"}}}},"storeName":{"type":"string","description":"Name of the Shopify store this product belongs to"},"storeId":{"type":"string","description":"ID of the store this product belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When the product was added to the catalog"},"updatedAt":{"type":"string","format":"date-time","description":"When the product was last updated"}}}}}}