openapi: 3.1.0
info:
  title: Curie 3D Product Commerce Catalog Products 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: []
tags:
- name: Products
paths:
  /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
      tags:
      - Products
  /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
      tags:
      - Products
  /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
      tags:
      - Products
  /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
      tags:
      - Products
  /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'
      tags:
      - Products
  /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'
      tags:
      - Products
components:
  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
  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