AI Import API

Start AI-powered import jobs to extract structured product data from documents and files.

Endpoints Overview

Create Import Job

Upload files and start a new AI import job.

Endpoint: POST /api/{organization}/ai-import-jobs/create

This endpoint accepts multipart/form-data.

Request Fields

Enrichment config fields:

Model Types

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@catalog.pdf" \
  -F "files=@products.csv" \
  -F "modelType=pro-v1" \
  -F "prompt=Extract product name, SKU, brand, and available colors" \
  -F "autoEnrich=false"

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "pending",
    "totalFiles": 2,
    "modelType": "pro-v1",
    "createdAt": "2026-04-18T10:00:00Z"
  }
}

List Import Jobs

Retrieve a paginated list of AI import jobs for your organization.

Endpoint: POST /api/{organization}/ai-import-jobs/get

Request Body

Example Request

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

Response

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "job_abc123",
        "status": "completed",
        "modelType": "pro-v1",
        "totalFiles": 2,
        "totalExtracted": 84,
        "createdAt": "2026-04-18T10:00:00Z",
        "completedAt": "2026-04-18T10:12:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "totalPages": 1
    }
  }
}

Job Status Values

Get Job Items

Retrieve the extracted products from an import job.

Endpoint: POST /api/{organization}/ai-import-jobs/{job_id}/items/get

Path Parameters

Request Body

Example Request

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

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "item_111",
        "type": "family",
        "status": "pending",
        "parentItemId": null,
        "data": {
          "name": "Wireless Headphones",
          "sku": "WH-PARENT",
          "brand": "AudioTech",
          "category": "Electronics",
          "manufacturer": null,
          "mpn": null,
          "variantOptions": {}
        },
        "errorMessage": null,
        "childCount": 2
      },
      {
        "id": "item_112",
        "type": "product",
        "status": "pending",
        "parentItemId": "item_111",
        "data": {
          "name": "Wireless Headphones - Black",
          "sku": "WH-001-BLK",
          "brand": "AudioTech",
          "category": "Electronics",
          "variantOptions": { "Color": "Black" }
        },
        "errorMessage": null,
        "childCount": 0
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 84,
      "totalPages": 2
    }
  }
}

Item Types

Item Status Values

Finalize Import Job

Import selected products into your catalog.

Endpoint: POST /api/{organization}/ai-import-jobs/{job_id}/finalize

You can call this multiple times on the same job to import products in batches.

Path Parameters

Request Body

Example Request

# Import specific items
curl -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/job_abc123/finalize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemIds": ["item_111", "item_112"]}'

# Import all pending items
curl -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/job_abc123/finalize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "imported": 42,
    "failed": 1
  }
}

Stop Import Job

Stop a running or pending import job. Already-extracted products are retained.

Endpoint: POST /api/{organization}/ai-import-jobs/{job_id}/stop

Path Parameters

Example Request

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

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "stopped"
  }
}

Only jobs with status pending or processing can be stopped.

Workflow Example

1. Start an import job

JOB_ID=$(curl -s -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@products.pdf" \
  -F "modelType=pro-v1" | jq -r '.data.jobId')

2. Poll until complete

while true; do
  STATUS=$(curl -s -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/get \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{}" | jq -r ".data.jobs[] | select(.id==\"$JOB_ID\") | .status")

  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done

3. Review and finalize

# Get extracted products
curl -s -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/$JOB_ID/items/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 200}'

# Import all into catalog
curl -X POST https://catalog-ai.tdcapps.com/api/your-org/ai-import-jobs/$JOB_ID/finalize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

See Also

• AI Import Guide — user guide for the review interface
• Authentication — API key setup
• Webhooks — get notified when jobs complete
• Products API — manage catalog products