Catalog AI
Sign In

Categories API

Look up, create, and read the enrichment history of product categories. Use these before starting a category enrichment job to avoid creating a duplicate, and after one to read what the job produced.

Category matching is case-insensitive throughout.

Endpoints

Method Endpoint Description
POST /product-categories/check Test whether a category name already exists
POST /product-categories/create Create a category, or return the existing one
POST /product-categories/enrichment-history Read enrichment results for a category name

Check a category

Endpoint: POST /api/{organization}/product-categories/check

Request

Field Type Required Description
name string Yes Category name to test 
curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-categories/check \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cordless Drills" }'

Response

{
  "success": true,
  "data": {
    "exists": false
  }
}

Create a category

Creates the category and returns it. When one with that name already exists, the existing record comes back with created: false, so this endpoint is safe to call repeatedly.

Endpoint: POST /api/{organization}/product-categories/create

Request

Field Type Required Description
name string Yes Category name
slug string No Derived from the name when omitted

As with brands, a slug collision appends a timestamp, so read the slug from the response rather than recomputing it.

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-categories/create \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cordless Drills" }'

Response

{
  "success": true,
  "data": {
    "category": {
      "id": "cat_abc123",
      "name": "Cordless Drills",
      "slug": "cordless-drills"
    },
    "created": true
  }
}

The record is returned under category, where the brands endpoint uses brand.

Category enrichment history

Returns every enrichment result recorded against a category name, newest first.

Endpoint: POST /api/{organization}/product-categories/enrichment-history

Request

Field Type Required Default Description
name string Yes Category name
page integer No 1 Page number, minimum 1
limit integer No 10 Items per page, 1 to 100

The limit ceiling here is 100. The equivalent brands endpoint caps at 50.

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-categories/enrichment-history \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cordless Drills", "page": 1, "limit": 10 }'

Response

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "pceji_abc123",
        "categoryName": "Cordless Drills",
        "referenceData": { "sources": ["https://example.com/drills"] },
        "completedAt": "2024-01-15T14:30:00Z",
        "createdAt": "2024-01-15T14:28:00Z",
        "modelType": "pro-v1",
        "status": "completed",
        "errorMessage": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

Category history items carry referenceData but no enrichedAttributes field. To read the generated copy and metadata, use the category enrichment job items endpoint.

Errors

Status Meaning
400 name missing or not a string, or pagination outside its bounds
401 No API key on the request
403 The key cannot reach this organization
500 Server error

Next steps