Skip to main content

​
Endpoint

POST /api/workspace/{workspaceId}/catalogs/{catalogId}/batch/gold
Triggers the Gold scoring stage for a selection of products or the entire catalog. Gold analyzes each product against a 7-stage rubric and produces an optimization score (0–100), a gap list, and a catalog-level summary.

​
Path parameters

ParameterTypeRequiredDescription
workspaceIdstringYesYour workspace ID
catalogIdstringYesThe catalog to analyze

​
Request body

{
  "productIds": ["prod_abc", "prod_def"],
  "scope": "selection"
}
FieldTypeRequiredDescription
productIdsstring[]NoProduct IDs to analyze. Required when scope is "selection"
scopestringYes"selection" or "all". When "all", productIds is ignored

​
Response

{
  "results": [
    {
      "productId": "prod_abc",
      "status": "success",
      "score": 82,
      "gaps": ["secondaryImages", "gtin"],
      "missingFields": ["gtin"]
    },
    {
      "productId": "prod_def",
      "status": "success",
      "score": 41,
      "gaps": ["description", "gtin", "brand", "images"],
      "missingFields": ["description", "gtin"]
    },
    {
      "productId": "prod_zzz",
      "status": "error",
      "error": "Product not in Silver stage — run Silver first"
    }
  ],
  "catalogSummary": {
    "avgScore": 61.5,
    "scoreDistribution": {
      "excellent": 12,
      "good": 34,
      "warning": 28,
      "poor": 8
    },
    "topGaps": ["gtin", "description", "secondaryImages"]
  }
}

​
GoldResult fields

FieldTypeDescription
productIdstringThe product that was analyzed
statusstring"success" or "error"
scorenumberOptimization score 0–100
gapsstring[]Fields ordered by score impact (highest impact first)
missingFieldsstring[]Fields completely absent (subset of gaps)
errorstringPresent only when status is "error"

​
catalogSummary fields

FieldTypeDescription
avgScorenumberMean optimization score across all processed products
scoreDistributionobjectCount per threshold: excellent (85–100), good (65–84), warning (40–64), poor (0–39)
topGapsstring[]Most common gaps across the catalog, ordered by frequency

​
Examples

# Analyze a selection
curl -X POST "https://app.alana.shopping/api/workspace/ws_123/catalogs/cat_456/batch/gold" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_abc", "prod_def"],
    "scope": "selection"
  }'

​
Analyze entire catalog

curl -X POST "https://app.alana.shopping/api/workspace/ws_123/catalogs/cat_456/batch/gold" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"scope": "all"}'

​
Score thresholds

RangeLabelMeaning
85–100ExcellentReady for all channels
65–84GoodMinor improvements recommended
40–64WarningImportant fields missing
0–39PoorCritical gaps — not feed-ready

​
Error responses

HTTP statusCodeDescription
400VALIDATION_ERRORscope is missing or invalid
403INSUFFICIENT_PERMISSIONSAPI key lacks catalogs:write
404CATALOG_NOT_FOUNDCatalog does not exist in workspace
409JOB_ALREADY_RUNNINGA batch job is already in progress
429RATE_LIMIT_EXCEEDEDBack off and retry after Retry-After header value
Products that have not been through Silver will return status: "error" with the message "Product not in Silver stage — run Silver first". Run Batch Silver before Gold for best results.
Last modified on March 18, 2026