Enrichment API

Start AI-powered enrichment jobs to automatically extract and enhance product data.

Endpoints Overview

Create Enrichment Job

Start a new enrichment job to process multiple products with AI.

Endpoint: POST /api/{organization}/product-enrichment-jobs/create

Request Body

Model Types

Parent Product Enrichment

Special Behavior for Parent Products:

When enriching products marked as parent products (products with variants):

• The system automatically enriches by aggregating data from all child product variants
• Web search is not used for parent products
• Parent products must have at least one child product with enriched attributes
• The enrichment aggregates common values, creates ranges for numeric data, and combines categorical values
• websearch and extractImages parameters are ignored for parent products
• includeExistingAttributes applies to the parent's own attributes. Child variant attributes are always used as the aggregation source
• Credit consumption is lower for parent products as they don't require web searches

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-enrichment-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_abc123", "prod_def456", "prod_ghi789"],
    "modelType": "pro-v1",
    "websearch": true,
    "extractImages": true
  }'

Response

{
  "success": true,
  "data": {
    "jobId": "job_xyz123",
    "status": "pending",
    "totalProducts": 3,
    "modelType": "pro-v1",
    "createdAt": "2024-01-15T14:00:00Z"
  }
}

List Enrichment Jobs

Retrieve a paginated list of enrichment jobs.

Endpoint: POST /api/{organization}/product-enrichment-jobs/get

Request Body

Example Request

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

Response

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "job_xyz123",
        "status": "completed",
        "modelType": "pro-v1",
        "websearch": true,
        "extractImages": false,
        "totalProducts": 3,
        "processedCount": 3,
        "successCount": 3,
        "failedCount": 0,
        "createdAt": "2024-01-15T14:00:00Z",
        "completedAt": "2024-01-15T14:05:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 15,
      "totalPages": 1
    }
  }
}

Job Status Values

Get Job Items

Retrieve detailed results for products within an enrichment job.

Endpoint: POST /api/{organization}/product-enrichment-jobs/{job_id}/items/get

Path Parameters

Request Body

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-enrichment-jobs/job_xyz123/items/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 20}'

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "item_aaa111",
        "jobId": "job_xyz123",
        "productId": "prod_abc123",
        "status": "completed",
        "startedAt": "2024-01-15T14:00:00Z",
        "completedAt": "2024-01-15T14:01:30Z",
        "errorMessage": null,
        "enrichedData": {
          "description": {
            "attributeId": "attr_desc",
            "attributeName": "Description",
            "attributeType": "html",
            "value": "Premium wireless headphones with noise cancellation"
          },
          "features": {
            "attributeId": "attr_features",
            "attributeName": "Features",
            "attributeType": "multiselect",
            "value": ["Bluetooth 5.0", "30h Battery", "Noise Cancellation"]
          }
        }
      },
      {
        "id": "item_bbb222",
        "jobId": "job_xyz123",
        "productId": "prod_def456",
        "status": "failed",
        "startedAt": "2024-01-15T14:01:30Z",
        "completedAt": "2024-01-15T14:02:00Z",
        "errorMessage": "Insufficient product data"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1
    }
  }
}

Item Status Values

Stop Enrichment Job

Stop a running or pending enrichment job. Any products already processed will retain their enriched data, but remaining products will not be processed.

Endpoint: POST /api/{organization}/product-enrichment-jobs/{job_id}/stop

Path Parameters

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-enrichment-jobs/job_xyz123/stop \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "message": "Enrichment job stopped successfully",
  "data": {
    "jobId": "job_xyz123",
    "status": "stopped"
  }
}

Error Response

If the job cannot be stopped (already completed, failed, or stopped):

{
  "success": false,
  "message": "Job cannot be stopped because it is not in progress"
}

Notes

• Only jobs with status pending or processing can be stopped
• The currently processing product will complete before the job stops
• A product_enrichment.stopped webhook event is triggered when a job is stopped
• Pending job items are marked as failed with the message "Job was stopped by user"

Workflow Example

1. Create Products

First, create products in your catalog:

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": "Wireless Headphones", "brand": "AudioCorp"},
      {"sku": "SKU-002", "name": "Bluetooth Speaker", "brand": "SoundMax"}
    ]
  }'

2. Start Enrichment Job

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-enrichment-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_abc123", "prod_def456"],
    "modelType": "pro-v1",
    "websearch": true,
    "extractImages": true
  }'

3. Monitor Job Status

Poll the jobs endpoint to check progress:

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-enrichment-jobs/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Get Results

Once completed, retrieve the enriched data:

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-enrichment-jobs/job_xyz123/items/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Best Practices

1. Batch Processing: Process products in batches of 100-500 for optimal performance
2. Monitor Progress: Poll job status every 5-10 seconds for large jobs
3. Handle Failures: Check individual item status for failed products
4. Use Webhooks: Set up webhooks for completion notifications
5. Choose Model Wisely: Use budget-v1 for testing, pro-v1 for production
6. Web Search Control: Set websearch: false when you have user-provided data sources to skip web search and reduce costs