AI Enrichment
AI Enrichment generates and improves product content — titles, descriptions, attributes, SEO fields, and translations — using large language models. Prompts live in a library you can customize; batch jobs and a web-search pipeline apply them at scale; every run is tracked for cost.
List prompts
Returns the prompt library: built-in prompts plus any custom prompts you created.
Query parameters
- Name
category- Type
- string
- Description
Filter by category (e.g.
description).
- Name
active_only- Type
- boolean
- Description
Return only prompts with
is_active: true.
Request
curl "https://api.pixeepim.com/api/v1/enrichment/prompts/?active_only=true" \
-H "Authorization: Bearer {api_key}"
Response
[
{
"slug": "seo-description-fr",
"name": "SEO description (FR)",
"category": "description",
"purpose": "descriptions",
"language": "fr",
"output_format": "text",
"is_active": true,
"sort_order": 100
}
]
Get a prompt
Returns the full definition of a prompt, including its system prompt and user prompt template.
Path parameters
- Name
slug- Type
- string
- Description
The prompt slug.
Request
curl https://api.pixeepim.com/api/v1/enrichment/prompts/seo-description-fr \
-H "Authorization: Bearer {api_key}"
Response
{
"slug": "seo-description-fr",
"name": "SEO description (FR)",
"category": "description",
"purpose": "descriptions",
"language": "fr",
"output_format": "text",
"system_prompt": "Tu es un rédacteur e-commerce spécialisé SEO.",
"user_prompt_template": "Rédige une description de {{title}} en {{language}}.",
"is_active": true,
"sort_order": 100
}
Create a custom prompt
Creates a custom prompt in the library, alongside the built-in ones.
Body parameters
- Name
slug- Type
- string
- Description
Lowercase identifier, 3–100 chars,
[a-z0-9_-]only.
- Name
name- Type
- string
- Description
Display name.
- Name
category- Type
- string
- Description
Free-form grouping label (default:
description).
- Name
purpose- Type
- string
- Description
One of
descriptions,categorize,seo,attributes,translate.
- Name
language- Type
- string
- Description
Prompt language, ISO 639-1 (default:
fr).
- Name
output_format- Type
- string
- Description
textor a structured format the enrichment pipeline understands (default:text).
- Name
system_prompt- Type
- string
- Description
System instructions sent to the model.
- Name
user_prompt_template- Type
- string
- Description
User message template; supports variable interpolation (e.g.
{{title}}).
- Name
is_active- Type
- boolean
- Description
Whether the prompt is selectable (default:
true).
- Name
sort_order- Type
- integer
- Description
Display order (default:
100).
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/prompts/ \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"slug": "seo-description-fr-v2",
"name": "SEO description (FR) v2",
"purpose": "descriptions",
"language": "fr",
"system_prompt": "Tu es un rédacteur e-commerce spécialisé SEO.",
"user_prompt_template": "Rédige une description de {{title}} en {{language}}, ton {{tone}}."
}'
Response
{
"slug": "seo-description-fr-v2",
"name": "SEO description (FR) v2",
"category": "description",
"purpose": "descriptions",
"language": "fr",
"output_format": "text",
"is_active": true,
"sort_order": 100
}
Update a prompt
Partially updates a prompt. Every field is optional and only provided fields are changed.
Path parameters
- Name
slug- Type
- string
- Description
The prompt slug.
Body parameters
- Name
name- Type
- string
- Description
Display name.
- Name
category- Type
- string
- Description
Grouping label.
- Name
purpose- Type
- string
- Description
One of
descriptions,categorize,seo,attributes,translate.
- Name
language- Type
- string
- Description
Prompt language.
- Name
output_format- Type
- string
- Description
Output format.
- Name
system_prompt- Type
- string
- Description
System instructions.
- Name
user_prompt_template- Type
- string
- Description
User message template.
- Name
is_active- Type
- boolean
- Description
Whether the prompt is selectable.
- Name
sort_order- Type
- integer
- Description
Display order.
Request
curl -X PATCH https://api.pixeepim.com/api/v1/enrichment/prompts/seo-description-fr-v2 \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{ "is_active": false }'
Response
{
"slug": "seo-description-fr-v2",
"name": "SEO description (FR) v2",
"is_active": false
}
Delete a prompt
Deletes a custom prompt. Built-in prompts cannot be deleted.
Path parameters
- Name
slug- Type
- string
- Description
The prompt slug.
Request
curl -X DELETE https://api.pixeepim.com/api/v1/enrichment/prompts/seo-description-fr-v2 \
-H "Authorization: Bearer {api_key}"
Execute a prompt on a product
Runs a specific prompt against a product, bypassing the normal resolution order. Useful for testing a prompt before binding it to an entity or group.
Path parameters
- Name
slug- Type
- string
- Description
The prompt slug to execute.
Body parameters
- Name
product_id- Type
- string
- Description
The product UUID to run the prompt against.
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/prompts/seo-description-fr/execute \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{ "product_id": "550e8400-e29b-41d4-a716-000000000001" }'
Response
{
"product_id": "550e8400-e29b-41d4-a716-000000000001",
"prompt_slug": "seo-description-fr",
"output": "Produit certifié CE conforme à la directive RoHS...",
"provider": "openai",
"model": "gpt-4o-mini"
}
Preview prompt resolution
Shows which prompt would actually run for a product, per enrichment type, without spending AI credits. This surfaces the resolution order used by POST /enrichment/products/{product_id}: an entity binding, then the group (base) binding, then the prompt library's default for that purpose, then a hard-coded constant fallback. Pass entity_id to preview resolution for that entity; omit it to preview the group (reference sheet) target.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Query parameters
- Name
entity_id- Type
- string
- Description
Preview resolution for this entity. Omitted = group (reference sheet) target.
- Name
types- Type
- array
- Description
Enrichment types (purposes) to preview.
rank in the response is the resolution level that matched (entity → group → library → constant, in that order) and binding_missing is true when no explicit binding exists and the library default or constant was used instead. When a prompt actually runs, its prompt_slug (and this rank) are recorded in the result's ai_metadata.
Request
curl "https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001/prompt-preview?types=descriptions&types=seo" \
-H "Authorization: Bearer {api_key}"
Response
{
"product_id": "550e8400-e29b-41d4-a716-000000000001",
"target": {
"layer": "group",
"entity_id": null,
"language": "fr",
"pivot_language": "fr"
},
"strict": false,
"written_to": "reference",
"prompts": [
{
"purpose": "descriptions",
"prompt_slug": "seo-description-fr",
"source": "library",
"rank": 3,
"origin": "default",
"binding_missing": true
}
]
}
Enrich a product
Triggers AI enrichment for a single product.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Query parameters
- Name
types- Type
- array
- Description
Enrichment types to run (default:
all).
- Name
auto_apply- Type
- boolean
- Description
If
true, writes the generated fields directly (default:true).
- Name
entity_id- Type
- string
- Description
Enrich for this entity instead of the reference sheet. Only
descriptionsandseoare accepted for an entity target; a422is returned if no prompt is bound to the entity. The result is written to the entity's own content variant — the group's reference sheet is never modified.
Request
curl -X POST "https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001?types=descriptions&types=seo&auto_apply=true" \
-H "Authorization: Bearer {api_key}"
Response
{
"product_id": "550e8400-e29b-41d4-a716-000000000001",
"descriptions": "Produit certifié CE conforme à la directive RoHS...",
"seo": { "title": "...", "meta_description": "..." },
"ai_metadata": {
"descriptions": { "prompt_slug": "seo-description-fr", "provider": "openai", "model": "gpt-4o-mini" }
}
}
Get product enrichment
Returns the stored enrichment data for a product.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Request
curl https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001 \
-H "Authorization: Bearer {api_key}"
Get enrichment progress
Polls the progress of an in-flight enrichment run for a product.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Request
curl https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001/progress \
-H "Authorization: Bearer {api_key}"
Response
{ "in_progress": false }
Apply enrichment fields
Applies previously generated enrichment fields to the product, when auto_apply was not used at generation time.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Query parameters
- Name
fields- Type
- array
- Description
Field names to apply from the last generated enrichment (e.g.
description,seo_title).
Request
curl -X POST "https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001/apply?fields=description&fields=seo_title" \
-H "Authorization: Bearer {api_key}"
Get enrichment history
Returns the history of enrichment changes applied to a product's fields.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Query parameters
- Name
limit- Type
- integer
- Description
Maximum number of history entries to return.
Request
curl "https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001/history?limit=10" \
-H "Authorization: Bearer {api_key}"
Response
[
{
"id": "b1e2...",
"enrichment_type": "description",
"previous_value": "Ancienne description",
"new_value": "Nouvelle description enrichie",
"provider": "openai",
"model": "gpt-4o-mini"
}
]
Enrich from documents (RAG)
Enriches a product from previously indexed documents (datasheets, certificates, manuals) using retrieval-augmented generation — no web search involved.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Query parameters
- Name
auto_apply- Type
- boolean
- Description
If
true, applies the enriched fields directly (default:false).
Request
curl -X POST "https://api.pixeepim.com/api/v1/enrichment/products/550e8400-e29b-41d4-a716-000000000001/from-documents?auto_apply=true" \
-H "Authorization: Bearer {api_key}"
Run the web enrichment pipeline
Runs the full web enrichment pipeline for a product: it retrieves indexed document chunks first (RAG, phase A), and only falls back to a live web search (phase B) when RAG returns fewer than 3 relevant chunks. Phase B is skipped by default — enable it explicitly if you want the pipeline to search the web when documents are insufficient.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Body parameters
- Name
skip_phase_a- Type
- boolean
- Description
Skip the RAG (document retrieval) phase (default:
false).
- Name
skip_phase_b- Type
- boolean
- Description
Skip the web search fallback phase (default:
true).
- Name
async_task- Type
- boolean
- Description
Run in the background and return immediately (default:
false).
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/web/products/550e8400-e29b-41d4-a716-000000000001/run \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{ "skip_phase_b": false, "async_task": true }'
Get web enrichment results
Returns the results of the web enrichment pipeline for a product, including which phase produced each field.
Path parameters
- Name
product_id- Type
- string
- Description
The product UUID.
Request
curl https://api.pixeepim.com/api/v1/enrichment/web/products/550e8400-e29b-41d4-a716-000000000001/results \
-H "Authorization: Bearer {api_key}"
Response
{
"product_id": "550e8400-e29b-41d4-a716-000000000001",
"rag_chunks_found": 2,
"used_web_search": true,
"phases": { "collect": "completed", "synthesize": "completed" }
}
Create a batch job
Creates and queues a batch enrichment job for a set of products.
Body parameters
- Name
name- Type
- string
- Description
Descriptive name for the job.
- Name
description- Type
- string
- Description
Optional longer description of the job's purpose.
- Name
filters- Type
- object
- Description
Filter object to select which products to enrich. Enriches all products if omitted.
- Name
enrichmentTypes- Type
- array
- Description
List of content types to generate (default:
["all"]).
- Name
priority- Type
- string
- Description
Optional queue priority.
- Name
maxBudget- Type
- number
- Description
Stop the job once this cost (USD) is reached.
- Name
scheduled_at- Type
- string
- Description
ISO 8601 datetime to schedule the job for later execution. Starts immediately if omitted.
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/batch \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"name": "SEO Descriptions – Active Products",
"filters": {"is_active": true},
"enrichmentTypes": ["description", "seo"],
"maxBudget": 20.0
}'
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SEO Descriptions – Active Products",
"status": "pending",
"total_products": 842,
"created_at": "2026-09-17T09:00:00Z"
}
List batch jobs
Returns batch enrichment jobs for the tenant.
Query parameters
- Name
status- Type
- string
- Description
Filter by status:
pending,running,completed,failed,paused,cancelled.
- Name
limit- Type
- integer
- Description
Maximum number of jobs to return (default: 20).
- Name
offset- Type
- integer
- Description
Pagination offset (default: 0).
Request
curl "https://api.pixeepim.com/api/v1/enrichment/batch?status=running&limit=20" \
-H "Authorization: Bearer {api_key}"
Get a batch job
Returns the current status and progress of a batch enrichment job.
Path parameters
- Name
job_id- Type
- string
- Description
The batch job UUID.
Request
curl https://api.pixeepim.com/api/v1/enrichment/batch/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer {api_key}"
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SEO Descriptions – Active Products",
"status": "completed",
"total_products": 842,
"processed": 842,
"failed": 3,
"created_at": "2026-09-17T09:00:00Z",
"completed_at": "2026-09-17T11:30:00Z"
}
Control a batch job
Starts, pauses, resumes, or cancels a batch enrichment job.
| Endpoint | Effect |
|---|---|
POST /enrichment/batch/{job_id}/start | Start a pending job |
POST /enrichment/batch/{job_id}/pause | Pause a running job |
POST /enrichment/batch/{job_id}/resume | Resume a paused job |
POST /enrichment/batch/{job_id}/cancel | Cancel a job |
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/batch/550e8400-e29b-41d4-a716-446655440000/start \
-H "Authorization: Bearer {api_key}"
Create a translation batch
Creates a batch translation job, or — with dry_run: true — only estimates its cost and scope without creating anything or writing any data.
Body parameters
- Name
filter- Type
- object
- Description
Product selection:
product_ids(explicit list, max 10 000), and/orbrand,active,category,missing_language— filters combine with AND withproduct_ids.
- Name
languages- Type
- array
- Description
Target languages, ISO 639-1, at least one.
- Name
entity_id- Type
- string
- Description
Write variants for this entity.
null(omitted) targets the group.
- Name
configuration_id- Type
- string
- Description
Restrict to a specific configuration's variants.
null(omitted) targets all.
- Name
fields- Type
- array
- Description
Fields to translate:
title,short_description,description,seo_title,seo_meta_description.
- Name
provider- Type
- string
- Description
auto(DeepL first, LLM fallback per variant on 429/5xx),deepl, orllm(default:auto).
- Name
overwrite_automatic- Type
- boolean
- Description
Rewrite automatic (unreviewed) variants. Reviewed variants are never overwritten (default:
false).
- Name
dry_run- Type
- boolean
- Description
Estimate only — no batch created, no writes (default:
false).
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/translate/batch \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"filter": {"active": true, "missing_language": "de"},
"languages": ["de", "es"],
"fields": ["title", "description", "seo_meta_description"],
"provider": "auto",
"dry_run": true
}'
Response (dry_run)
{
"products": 420,
"variants": 840,
"characters": 315000,
"estimated_cost": 18.9,
"currency": "EUR",
"provider": "auto"
}
List translation batches
Returns translation batches for the tenant, most recent first.
Query parameters
- Name
limit- Type
- integer
- Description
Maximum number of batches to return.
Request
curl "https://api.pixeepim.com/api/v1/enrichment/translate/batch?limit=20" \
-H "Authorization: Bearer {api_key}"
Get translation batch progress
Returns a translation batch and its progress.
Path parameters
- Name
job_id- Type
- string
- Description
The translation batch UUID.
Request
curl https://api.pixeepim.com/api/v1/enrichment/translate/batch/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer {api_key}"
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"languages": ["de", "es"],
"fields": ["title", "description", "seo_meta_description"],
"provider": "auto",
"status": "running",
"products": 420,
"total": 840,
"done": 512,
"failed": 3,
"skipped": 40,
"estimate": { "products": 420, "variants": 840, "characters": 315000, "estimated_cost": 18.9, "currency": "EUR", "provider": "auto" },
"cursor": "550e8400-e29b-41d4-a716-000000000201"
}
Control a translation batch
Pauses or resumes a translation batch. Pausing keeps the cursor in place; resuming continues from it — nothing already written is retranslated.
| Endpoint | Effect |
|---|---|
POST /enrichment/translate/batch/{job_id}/pause | Suspend the batch, cursor preserved |
POST /enrichment/translate/batch/{job_id}/resume | Resume from the cursor |
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/translate/batch/550e8400-e29b-41d4-a716-446655440000/pause \
-H "Authorization: Bearer {api_key}"
Get translation review rows
Returns the batch's review rows — one row per (product, language, field) — with the source (pivot) text and the translated variant text, for manual review.
Path parameters
- Name
job_id- Type
- string
- Description
The translation batch UUID.
Query parameters
- Name
language- Type
- string
- Description
Filter rows by target language.
- Name
reviewed- Type
- boolean
- Description
Filter by review status.
- Name
max_score- Type
- number
- Description
Only rows with a quality score at or below this value (surfaces the rows most worth reviewing).
- Name
page- Type
- integer
- Description
Page number.
- Name
per_page- Type
- integer
- Description
Items per page.
Request
curl "https://api.pixeepim.com/api/v1/enrichment/translate/batch/550e8400-e29b-41d4-a716-446655440000/items?language=de&reviewed=false" \
-H "Authorization: Bearer {api_key}"
Response
{
"items": [
{
"id": "it_01",
"product_id": "550e8400-e29b-41d4-a716-000000000001",
"product_name": "Produit exemple",
"language": "de",
"pivot_language": "fr",
"field": "title",
"pivot_text": "Produit exemple",
"variant_text": "Beispielprodukt",
"quality_score": 0.91,
"reviewed": false,
"provider": "deepl"
}
],
"total": 840,
"page": 1,
"per_page": 50
}
Get enrichment stats
Returns aggregate enrichment coverage statistics for the catalog.
Request
curl https://api.pixeepim.com/api/v1/enrichment/stats \
-H "Authorization: Bearer {api_key}"
Get enrichment analytics
Returns enrichment activity analytics over a time window.
Query parameters
- Name
days- Type
- integer
- Description
Number of days to include.
Request
curl "https://api.pixeepim.com/api/v1/enrichment/analytics?days=30" \
-H "Authorization: Bearer {api_key}"
Estimate batch cost
Estimates the token usage, cost, and duration of a batch enrichment run without spending any credits (dry-run).
Body parameters
- Name
product_ids- Type
- array
- Description
Explicit product UUIDs to estimate for.
- Name
filters- Type
- object
- Description
Filter object to select products, as an alternative to
product_ids.
- Name
enrichment_types- Type
- array
- Description
Types to estimate (default:
["web_enrichment"]).
- Name
provider- Type
- string
- Description
AI provider to price against (default:
openai).
- Name
model- Type
- string
- Description
Model to price against (default:
gpt-4o).
Request
curl -X POST https://api.pixeepim.com/api/v1/enrichment/web/batch/estimate \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"filters": {"is_active": true},
"enrichment_types": ["description", "seo"],
"provider": "openai",
"model": "gpt-4o-mini"
}'
Response
{
"products_count": 842,
"enrichment_types": ["description", "seo"],
"estimated_tokens": { "input": 505200, "output": 168400, "total": 673600 },
"estimated_cost_usd": 6.42,
"estimated_cost_eur": 5.91,
"avg_cost_per_product_eur": 0.007,
"estimated_duration_minutes": 42.1,
"provider": "openai",
"model": "gpt-4o-mini",
"breakdown": {
"description": { "input_tokens": 336800, "output_tokens": 84200, "cost_usd": 4.28 },
"seo": { "input_tokens": 168400, "output_tokens": 84200, "cost_usd": 2.14 }
}
}
Get cost summary
Returns actual AI spend for enrichment over a time window, broken down by provider and by action, with an estimate of savings from smart routing.
Query parameters
- Name
days- Type
- integer
- Description
Number of days to include (default: 30, max 365).
Request
curl "https://api.pixeepim.com/api/v1/enrichment/web/costs/summary?days=30" \
-H "Authorization: Bearer {api_key}"
Response
{
"period_days": 30,
"total_cost_usd": 124.5,
"total_cost_eur": 114.54,
"by_provider": [
{ "provider": "openai", "cost_usd": 98.2, "count": 4100 },
{ "provider": "anthropic", "cost_usd": 26.3, "count": 900 }
],
"by_action": [
{ "action": "description", "cost_usd": 60.1, "count": 2200 },
{ "action": "translate", "cost_usd": 40.4, "count": 1500 }
],
"smart_routing_savings": {
"tasks": 5000,
"baseline_cost": 210.0,
"optimized_cost": 124.5,
"saved": 85.5,
"savings_percent": 40.7
}
}