Products API

Manage products in your catalog.

Endpoints Overview

Method	Endpoint	Description
POST	`/products/create`	Create a single product
POST	`/products/bulk-create`	Create multiple products
POST	`/products/get`	List products with pagination
POST	`/products/{product_id}/get`	Get a single product
POST	`/products/{product_id}/update`	Update a product
POST	`/products/{product_id}/delete`	Delete a product
POST	`/products/{product_id}/update-attributes`	Update product attributes
POST	`/products/{product_id}/enrichment-history`	Get enrichment history
POST	`/products/{product_id}/validation-history`	Get validation history

Create Product

Add a new product to your catalog.

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

Request Body

Field	Type	Required	Description
`sku`	string	Yes	Product SKU (max 64 characters)
`name`	string	Yes	Product name (max 256 characters)
`manufacturer`	string	No	Manufacturer name (max 256 characters)
`mpn`	string	No	Manufacturer Part Number (max 128 characters)
`uom`	string	No	Unit of measure (max 128 characters)
`brand`	string	No	Brand name (max 128 characters)
`category`	string	No	Product category
`externalId`	string	No	External identifier for your reference
`parentId`	string	No	Parent product ID (for product variants)
`isParent`	boolean	No	Mark as parent product (default: false)
`userProvidedRawDataSources`	string[]	No	URLs or references for product information
`attributes`	object	No	Pre-structured product attributes

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.tdcapps.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.tdcapps.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.tdcapps.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

Field	Type	Required	Description
`products`	array	Yes	Array of product objects (max 1000)

Each product object follows the same structure as Create Product.

Example Request

curl -X POST https://catalog-ai.tdcapps.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

Field	Type	Required	Default	Description
`page`	number	No	1	Page number
`limit`	number	No	10	Items per page (max 100)
`search`	string	No	""	Search term
`sortBy`	string	No	"createdAt"	Sort field: `sku`, `name`, `manufacturer`, `brand`, `createdAt`
`sortOrder`	string	No	"desc"	Sort direction: `asc` or `desc`
`parentFilter`	string	No	"all"	Filter: `all`, `parent`, or `non-parent`
`enrichedFilter`	string	No	"all"	Filter: `all`, `enriched`, or `not-enriched`

Example Request

curl -X POST https://catalog-ai.tdcapps.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.tdcapps.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.tdcapps.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"
  }'

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

Parameter	Type	Required	Description
`product_id`	string	Yes	Product ID

Example Request

curl -X POST https://catalog-ai.tdcapps.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

Parameter	Type	Required	Description
`product_id`	string	Yes	Product ID

Request Body

Field	Type	Required	Description
`sku`	string	Yes	Product SKU (max 64 characters)
`name`	string	Yes	Product name (max 256 characters)
`manufacturer`	string	No	Manufacturer name
`mpn`	string	No	Manufacturer Part Number
`brand`	string	No	Brand name
`category`	string	No	Product category
`externalId`	string	No	External identifier
`parentId`	string	No	Parent product ID
`isParent`	boolean	No	Mark as parent product
`userProvidedRawDataSources`	string[]	No	Data source URLs

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

Example Request

curl -X POST https://catalog-ai.tdcapps.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

Parameter	Type	Required	Description
`product_id`	string	Yes	Product ID

Example Request

curl -X POST https://catalog-ai.tdcapps.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

Parameter	Type	Required	Description
`product_id`	string	Yes	Product ID or external ID

Request Body

Field	Type	Required	Description
`attributes`	object	Yes	Key-value pairs of attributes

Attribute Object Structure

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

Attribute Types

Type	Value Format	Example
`text`	String	`"Blue"`
`html`	HTML string	`"<p>Description</p>"`
`number`	Number	`250`
`boolean`	Boolean	`true`
`date`	ISO date string	`"2024-01-15T00:00:00Z"`
`select`	String	`"Option A"`
`multiselect`	Array of strings	`["A", "B"]`

Example Request

curl -X POST https://catalog-ai.tdcapps.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

Parameter	Type	Required	Description
`product_id`	string	Yes	Product ID

Request Body

Field	Type	Required	Default	Description
`page`	number	No	1	Page number
`limit`	number	No	10	Items per page (max 100)

Example Request

curl -X POST https://catalog-ai.tdcapps.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

Parameter	Type	Required	Description
`product_id`	string	Yes	Product ID

Request Body

Field	Type	Required	Default	Description
`page`	number	No	1	Page number
`limit`	number	No	10	Items per page (max 100)

Example Request

curl -X POST https://catalog-ai.tdcapps.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"
}