Enrichment
AI-powered catalog enrichment using your own LLM. Skirre analyzes product data and generates tag suggestions, category inference, attribute extraction, search term expansion, and listing quality scores. You provide the LLM API key — Skirre handles the orchestration.
Trigger a batch catalog enrichment job. Runs asynchronously in the background.
Request body
| Parameter | Type | Description |
|---|---|---|
| batch_size optional | number | Maximum documents to process. Overrides the batch_size in enrichment settings for this run. |
Example
curl -X POST https://search.example.com/v1/indices/products/enrichment/run \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "batch_size": 50 }'
SDK
const job = await idx.runEnrichment({ batch_size: 50 }); console.log(job.job_id); // "enr_job_abc123..."
Response 201 Created
{
"job_id": "enr_job_a1b2c3d4e5f6",
"status": "pending",
"total_docs": 50
}409 Conflict.List enrichment jobs for an index, newest first.
Example
curl https://search.example.com/v1/indices/products/enrichment/jobs \
-H "Authorization: Bearer sk_search_live_..."SDK
const jobs = await idx.getEnrichmentJobs();
Response 200 OK
{
"jobs": [
{
"id": "enr_job_a1b2c3d4e5f6",
"index_uid": "products",
"status": "completed",
"total_docs": 50,
"processed_docs": 50,
"suggestions_count": 127,
"error": null,
"created_at": "2026-10-08T14:30:00Z",
"completed_at": "2026-10-08T14:32:15Z"
}
]
}Job fields
| Parameter | Type | Description |
|---|---|---|
| id required | string | Job ID. |
| index_uid required | string | Index this job belongs to. |
| status required | string | One of: pending, running, completed, failed. |
| total_docs required | number | Total documents in the batch. |
| processed_docs required | number | Documents processed so far. |
| suggestions_count required | number | Number of suggestions generated. |
| error required | string | null | Error message if the job failed. |
| created_at required | string | ISO 8601 timestamp. |
| completed_at required | string | null | ISO 8601 timestamp when the job finished. |
Get enrichment job status and progress.
Example
curl https://search.example.com/v1/indices/products/enrichment/jobs/enr_job_a1b2c3d4e5f6 \
-H "Authorization: Bearer sk_search_live_..."SDK
const job = await idx.getEnrichmentJob('enr_job_a1b2c3d4e5f6'); console.log(job.processed_docs, '/', job.total_docs);
Response 200 OK
Same shape as a single item in the jobs list response above.
List enrichment suggestions with optional filters by status, type, and document.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| status optional | string | Filter by status: pending, applied, or dismissed. |
| suggestion_type optional | string | Filter by type: tags, category, attributes, search_terms, or quality. |
| document_id optional | string | Filter by document ID. |
| limit optional | number | Maximum results to return. Default: 50 |
| offset optional | number | Number of results to skip. Default: 0 |
Example
curl "https://search.example.com/v1/indices/products/enrichment/suggestions?status=pending&limit=20" \
-H "Authorization: Bearer sk_search_live_..."SDK
const result = await idx.getEnrichmentSuggestions({ status: 'pending', suggestion_type: 'tags', limit: 20, });
Response 200 OK
{
"suggestions": [
{
"id": "enr_sug_x1y2z3",
"job_id": "enr_job_a1b2c3d4e5f6",
"document_id": "prod_abc123",
"suggestion_type": "tags",
"suggestion_data": { "tags": ["helix piercing", "cartilage earring"] },
"confidence": 0.85,
"status": "pending",
"created_at": "2026-10-08T14:31:02Z",
"resolved_at": null
}
],
"total": 1
}Suggestion fields
| Parameter | Type | Description |
|---|---|---|
| id required | string | Suggestion ID. |
| job_id required | string | The enrichment job that generated this suggestion. |
| document_id required | string | The document this suggestion applies to. |
| suggestion_type required | string | One of: tags, category, attributes, search_terms, quality. |
| suggestion_data required | object | Structured data for the suggestion. Shape depends on type (see Suggestion types below). |
| confidence required | number | Confidence score between 0 and 1. |
| status required | string | One of: pending, applied, dismissed. |
| created_at required | string | ISO 8601 timestamp. |
| resolved_at required | string | null | ISO 8601 timestamp when applied or dismissed. |
Apply a suggestion to the document. Merges enrichment data into the Tantivy document and re-computes embeddings.
Example
curl -X POST https://search.example.com/v1/indices/products/enrichment/suggestions/enr_sug_x1y2z3/apply \
-H "Authorization: Bearer sk_search_live_..."SDK
await idx.applyEnrichmentSuggestion('enr_sug_x1y2z3');
Response 200 OK
{
"id": "enr_sug_x1y2z3",
"status": "applied"
}400.Dismiss a suggestion without applying it.
Example
curl -X POST https://search.example.com/v1/indices/products/enrichment/suggestions/enr_sug_x1y2z3/dismiss \
-H "Authorization: Bearer sk_search_live_..."SDK
await idx.dismissEnrichmentSuggestion('enr_sug_x1y2z3');
Response 200 OK
{
"id": "enr_sug_x1y2z3",
"status": "dismissed"
}Batch apply or dismiss multiple suggestions at once. Maximum 100 per request.
Request body
| Parameter | Type | Description |
|---|---|---|
| ids required | string[] | Array of suggestion IDs to resolve. Max 100. |
| action required | string | Either "applied" or "dismissed". |
Example
curl -X POST https://search.example.com/v1/indices/products/enrichment/suggestions/batch \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "ids": ["enr_sug_x1y2z3", "enr_sug_a4b5c6"], "action": "applied" }'
SDK
const result = await idx.batchResolveEnrichmentSuggestions({ ids: ['enr_sug_x1y2z3', 'enr_sug_a4b5c6'], action: 'applied', }); console.log(result.resolved); // 2
Response 200 OK
{
"resolved": 2
}action is "applied", each suggestion is merged into its
document before being marked as applied. Suggestions that are already resolved or belong
to a different index are skipped silently.Configuration
Enrichment is configured per-index via the enrichment key in index settings. You must provide your own LLM API key —
Skirre does not include an LLM.
await idx.updateSettings({ enrichment: { enabled: true, provider: { base_url: 'https://api.openai.com/v1', api_key: 'sk-...', model: 'gpt-4o-mini', max_tokens: 2048, }, mode: 'suggest', confidence_threshold: 0.8, batch_size: 100, categories: ['Earrings', 'Necklaces', 'Rings'], }, });
Enrichment settings
| Parameter | Type | Description |
|---|---|---|
| enabled required | boolean | Whether enrichment is active for this index. |
| provider required | object | LLM provider configuration (see below). |
| mode optional | string | "suggest" (default) or "auto_apply". See Modes below. Default: "suggest" |
| confidence_threshold optional | number | Minimum confidence for auto-apply mode (0.0 to 1.0). Default: 0.8 |
| batch_size optional | number | Default number of documents per enrichment run. Default: 100 |
| categories optional | string[] | Valid category names for category inference. If provided, the LLM will only suggest from this list. |
Provider settings
| Parameter | Type | Description |
|---|---|---|
| base_url required | string | Base URL of the OpenAI-compatible API (e.g. https://api.openai.com/v1). |
| api_key required | string | API key for the LLM provider. Stored securely, redacted in GET responses. |
| model required | string | Model name (e.g. gpt-4o-mini, claude-3-haiku-20240307). |
| max_tokens optional | number | Maximum tokens for the LLM response. Default: 2048 |
response_format: { type: "json_object" }).Suggestion types
Each enrichment run can generate up to five types of suggestions per document:
Tags
Inferred tags based on product title, description, and existing metadata. Useful for improving search discoverability.
{ "tags": ["helix piercing", "cartilage earring", "gold jewelry"] }Category
Suggested category for uncategorized or miscategorized products. Constrained to your category list if configured.
{ "category": "Earrings > Helix" }Attributes
Extracted key-value attributes from product text (material, style, occasion, etc.).
{ "attributes": { "material": "14K Gold", "gauge": "16g" } }Search terms
Additional search terms derived from the product content. These are stored in the document to improve search recall.
{ "terms": ["curved barbell", "body jewelry", "piercing jewelry"] }Quality
Listing quality score and issues. Flags products with missing images, short descriptions, no tags, etc. Quality suggestions are never auto-applied.
{
"score": 0.65,
"issues": ["Description under 50 characters", "No tags"]
}Modes
Suggest mode (default)
All suggestions are created with status: "pending" and wait for manual review.
Use the dashboard or API to apply or dismiss each suggestion.
Auto-apply mode
Suggestions with confidence at or above confidence_threshold are automatically
applied to the document during the enrichment run. The suggestion is still recorded (with status: "applied") for auditability. Suggestions below the threshold remain
pending for manual review.
Quality suggestions are never auto-applied regardless of mode — they are informational only.
When a suggestion is applied (manually or automatically), Skirre:
- Loads the current document from the index.
- Merges the enrichment data into prefixed fields (
_enrichment_tags,_enrichment_category,_enrichment_attributes,_enrichment_search_terms,_enrichment_quality_score). - Re-computes embeddings for the updated document.
- Writes the document back to the index.