> ## Documentation Index
> Fetch the complete documentation index at: https://docs.facetflux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrichment

> Fill missing specs, normalize values, and classify products with AI — every value comes with a source.

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**:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.facetflux.com/api/v1/pim/products/$PRODUCT_ID/enrich?mode=enhanced" \
    -H "Authorization: Bearer $FACETFLUX_API_KEY"
  ```

  ```python Python theme={null}
  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']})")
  ```
</CodeGroup>

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.

<Warning>
  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.
</Warning>

## Accept or reject

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

```bash theme={null}
# 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 Python theme={null}
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")
```

<Note>
  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](https://facetflux.com/pricing) for rates.
</Note>

<Tip>
  Running at scale without writing a loop? The [MCP server](/mcp) exposes these same operations as agent tools with idempotent, per-product writes.
</Tip>