Products API

Manage products in your catalog.

Endpoints Overview

Create Product

Add a new product to your catalog.

Endpoint: POST /api/{organization}/products/create

Request Body

Note: A product cannot have both isParent: true and a parentId. Parent products cannot be variants of other products.

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU-12345",
    "name": "Wireless Headphones",
    "manufacturer": "AudioCorp",
    "brand": "AudioCorp Pro",
    "mpn": "WH-1000",
    "category": "Electronics > Audio > Headphones"
  }'

Example: Creating a Parent Product

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-CLASSIC",
    "name": "Classic T-Shirt",
    "brand": "MyBrand",
    "category": "Apparel",
    "isParent": true
  }'

Example: Creating a Variant Product

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-CLASSIC-RED-M",
    "name": "Classic T-Shirt - Red, Medium",
    "brand": "MyBrand",
    "category": "Apparel",
    "parentId": "prod_parent123"
  }'

Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "sku": "SKU-12345",
    "name": "Wireless Headphones",
    "manufacturer": "AudioCorp",
    "brand": "AudioCorp Pro",
    "mpn": "WH-1000",
    "category": "Electronics > Audio > Headphones",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Bulk Create Products

Add multiple products at once. Maximum 1000 products per request.

Endpoint: POST /api/{organization}/products/bulk-create

Request Body

Each product object follows the same structure as Create Product.

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/bulk-create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "sku": "SKU-001",
        "name": "Product One",
        "brand": "BrandA"
      },
      {
        "sku": "SKU-002",
        "name": "Product Two",
        "brand": "BrandB"
      }
    ]
  }'

Response

{
  "success": true,
  "data": {
    "created": true
  }
}

Error: Duplicate SKU

{
  "success": false,
  "message": "Products with these SKUs/externalIds already exist: SKU-001"
}

List Products

Retrieve a paginated list of products.

Endpoint: POST /api/{organization}/products/get

Request Body

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20,
    "search": "headphones",
    "sortBy": "name",
    "sortOrder": "asc"
  }'

Example: List Only Parent Products

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20,
    "parentFilter": "parent"
  }'

Example: List Products That Have Not Been Enriched

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20,
    "enrichedFilter": "not-enriched"
  }'

Example: List Products That Need Review

A product needs review when any AI-enriched value has Medium or Low confidence.

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20,
    "confidenceFilter": "needs-review"
  }'

Filter Rules

Each rule has a field, an operator and, for most operators, a value. Rules apply on top of search, parentFilter, enrichedFilter and confidenceFilter. Text comparisons ignore case. Dates are YYYY-MM-DD in UTC.

Example: Filter by Rules

This request lists products from either of two brands that have a voltage of at least 18 and were not enriched in the last 30 days:

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "match": "all",
    "rules": [
      { "field": "enrichBrand", "operator": "is_any_of", "values": ["brand_abc", "brand_def"] },
      { "field": "attribute", "attribute": "voltage", "operator": "gte", "value": "18" },
      { "field": "enrichedAt", "operator": "before", "value": "2026-10-06" }
    ]
  }'

Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_abc123",
        "sku": "SKU-12345",
        "name": "Wireless Headphones",
        "manufacturer": "AudioCorp",
        "brand": "AudioCorp Pro",
        "category": "Electronics > Audio > Headphones",
        "parentId": null,
        "parentName": null,
        "isParent": false,
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Get Product

Retrieve details of a specific product.

Endpoint: POST /api/{organization}/products/{product_id}/get

Path Parameters

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/prod_abc123/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "sku": "SKU-12345",
    "name": "Wireless Headphones",
    "manufacturer": "AudioCorp",
    "brand": "AudioCorp Pro",
    "mpn": "WH-1000",
    "category": "Electronics > Audio > Headphones",
    "parentId": null,
    "isParent": false,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Update Product

Update an existing product.

Endpoint: POST /api/{organization}/products/{product_id}/update

Path Parameters

Request Body

Note: A product cannot have both isParent: true and a parentId.

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/prod_abc123/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU-12345",
    "name": "Wireless Noise-Canceling Headphones",
    "brand": "AudioCorp Pro Max"
  }'

Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "sku": "SKU-12345",
    "name": "Wireless Noise-Canceling Headphones",
    "brand": "AudioCorp Pro Max",
    "updatedAt": "2024-01-15T11:30:00Z"
  }
}

Delete Product

Remove a product from your catalog.

Endpoint: POST /api/{organization}/products/{product_id}/delete

Path Parameters

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/prod_abc123/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "deleted": true
  }
}

Update Product Attributes

Update custom attributes for a product.

Endpoint: POST /api/{organization}/products/{product_id}/update-attributes

Path Parameters

Request Body

Attribute Object Structure

{
  "attribute_key": {
    "attributeId": "string",
    "attributeName": "string",
    "attributeType": "text|html|number|date|boolean|select|multiselect",
    "value": "any"
  }
}

Confidence

Values filled by AI enrichment also carry a read-only confidence object:

{
  "level": "high",
  "basis": "manufacturer",
  "sources": [
    {
      "name": "acme.com",
      "url": "https://acme.com/p/123",
      "isManufacturer": true
    }
  ]
}

• level is high, medium, or low.
• basis is manufacturer, sources_agree, few_sources, sources_conflict, no_source, or variants.
• sources lists the sources that support the value. An uploaded file has a url of null.

This endpoint ignores any confidence you send. A value you leave unchanged keeps its confidence. A value you change loses it, because it is no longer AI output.

Attribute Types

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/prod_abc123/update-attributes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "color": {
        "attributeId": "attr_color",
        "attributeName": "Color",
        "attributeType": "text",
        "value": "Black"
      },
      "weight": {
        "attributeId": "attr_weight",
        "attributeName": "Weight (grams)",
        "attributeType": "number",
        "value": 250
      }
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "sku": "SKU-12345",
    "name": "Wireless Headphones",
    "attributes": {
      "color": {
        "attributeId": "attr_color",
        "attributeName": "Color",
        "attributeType": "text",
        "value": "Black"
      },
      "weight": {
        "attributeId": "attr_weight",
        "attributeName": "Weight (grams)",
        "attributeType": "number",
        "value": 250
      }
    },
    "updatedAt": "2024-01-15T11:45:00Z"
  }
}

Get Enrichment History

Retrieve the enrichment history for a product.

Endpoint: POST /api/{organization}/products/{product_id}/enrichment-history

Path Parameters

Request Body

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/prod_abc123/enrichment-history \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 10}'

Response

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "hist_xyz789",
        "productId": "prod_abc123",
        "enrichedAt": "2024-01-15T12:00:00Z",
        "attributes": {
          "description": {
            "attributeId": "attr_desc",
            "attributeName": "Description",
            "attributeType": "html",
            "value": "Premium wireless headphones with noise cancellation"
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "totalPages": 1
    }
  }
}

Get Validation History

Retrieve the validation history for a product.

Endpoint: POST /api/{organization}/products/{product_id}/validation-history

Path Parameters

Request Body

Example Request

curl -X POST https://catalog-ai.tdccommerce.com/api/your-org/products/prod_abc123/validation-history \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 10}'

Response

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "val_hist_xyz789",
        "productId": "prod_abc123",
        "validatedAt": "2024-01-15T12:00:00Z",
        "overallScore": 85.5
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 3,
      "totalPages": 1
    }
  }
}

Error Responses

400 Bad Request

Invalid request parameters.

{
  "success": false,
  "message": "Invalid request body: ..."
}

404 Not Found

Product does not exist.

{
  "success": false,
  "message": "Product not found"
}