Enrichment

Enrichment runs AI over a product and proposes attribute values: filled specifications, normalized units, generated descriptions, classifications. Suggestions are returned for you to accept or reject — nothing overwrites your data until you say so. Every suggestion carries a reasoning and a confidence.

Modes

Each enrichment call takes a mode that controls how much evidence the AI gathers — and how much it costs per product:

Mode	Uses	Best for
`standard`	Product images + existing attribute values	Fast, cheap passes on data you mostly have
`enhanced`	Everything in standard, plus linked PDFs and document URLs	Products with datasheets attached
`deep`	Everything in enhanced, plus web search of the product page	Sparse products that need outside data

Enrich a single product

POST /api/v1/pim/products/{productId}/enrich?mode=standard runs synchronously and returns a suggestion:

curl -X POST "https://app.facetflux.com/api/v1/pim/products/$PRODUCT_ID/enrich?mode=enhanced" \
  -H "Authorization: Bearer $FACETFLUX_API_KEY"

resp = requests.post(
    f"https://app.facetflux.com/api/v1/pim/products/{product_id}/enrich",
    params={"mode": "enhanced"},
    headers={"Authorization": f"Bearer {os.environ['FACETFLUX_API_KEY']}"},
)
resp.raise_for_status()
suggestion = resp.json()
for code, field in suggestion["fieldSuggestions"].items():
    print(code, "→", field["value"], f"({field['confidence']})")

The response is a PimEnrichmentSuggestion with a fieldSuggestions map, keyed by attribute code. Each entry has the proposed value, a reasoning string, a confidence (0–1), and accepted / rejected flags.

A 200 response can still carry a non-completed status — check status == "completed" and errorMessage before trusting the suggestions. Values are only charged and returned when enrichment actually completes.

Accept or reject

Suggestions don’t change your product until you accept them:

# Accept one field
curl -X POST ".../enrichment/$SUGGESTION_ID/accept" \
  -H "Authorization: Bearer $FACETFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "attributeCode": "length_mm" }'

# Accept everything
curl -X POST ".../enrichment/$SUGGESTION_ID/accept" \
  -H "Authorization: Bearer $FACETFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "all": true }'

Rejecting works the same way but always needs a specific attributeCode.

Estimate and batch

Before a large run, POST /api/v1/pim/products/enrichment/estimate with a list of productIds and a mode tells you whether you can proceed — it returns creditsRequired, creditsAvailable, and canProceed, and does no AI work. To enrich many products, POST /api/v1/pim/products/enrichment/batch accepts up to 200 productIds. It processes them sequentially and returns per-product results, successCount, and failedCount.

Python

resp = requests.post(
    "https://app.facetflux.com/api/v1/pim/products/enrichment/batch",
    headers={"Authorization": f"Bearer {os.environ['FACETFLUX_API_KEY']}"},
    json={"productIds": product_ids[:200], "mode": "standard"},
)
resp.raise_for_status()
print(resp.json()["successCount"], "enriched")

Enrichment is billed per product; reads are free. Cost scales with mode (enhanced and deep cost more than standard). Enrichment responses include x-credits-left and x-credits-used headers so you can track usage. See pricing for rates.

Running at scale without writing a loop? The MCP server exposes these same operations as agent tools with idempotent, per-product writes.

Get started

Guides

AI & agents

Modes

Enrich a single product

Accept or reject

Estimate and batch

​Modes

​Enrich a single product

​Accept or reject

​Estimate and batch

Modes

Enrich a single product

Accept or reject

Estimate and batch