openapi: 3.1.0
info:
  title: Curie 3D Product Commerce Catalog 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: Catalog
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)
      tags:
      - Catalog
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