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.

Note
All enrichment endpoints require an admin key. Search keys cannot trigger enrichment or access suggestions.
POST /v1/indices/{uid}/enrichment/run Admin key

Trigger a batch catalog enrichment job. Runs asynchronously in the background.

Request body

ParameterTypeDescription
batch_size optionalnumberMaximum documents to process. Overrides the batch_size in enrichment settings for this run.

Example

text
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

text
const job = await idx.runEnrichment({ batch_size: 50 });
console.log(job.job_id); // "enr_job_abc123..."

Response 201 Created

text
{
  "job_id": "enr_job_a1b2c3d4e5f6",
  "status": "pending",
  "total_docs": 50
}
Note
Only one enrichment job can run at a time per index. Attempting to start a second job while one is pending or running returns 409 Conflict.
GET /v1/indices/{uid}/enrichment/jobs Admin key

List enrichment jobs for an index, newest first.

Example

text
curl https://search.example.com/v1/indices/products/enrichment/jobs \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const jobs = await idx.getEnrichmentJobs();

Response 200 OK

text
{
  "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

ParameterTypeDescription
id requiredstringJob ID.
index_uid requiredstringIndex this job belongs to.
status requiredstringOne of: pending, running, completed, failed.
total_docs requirednumberTotal documents in the batch.
processed_docs requirednumberDocuments processed so far.
suggestions_count requirednumberNumber of suggestions generated.
error requiredstring | nullError message if the job failed.
created_at requiredstringISO 8601 timestamp.
completed_at requiredstring | nullISO 8601 timestamp when the job finished.
GET /v1/indices/{uid}/enrichment/jobs/{job_id} Admin key

Get enrichment job status and progress.

Example

text
curl https://search.example.com/v1/indices/products/enrichment/jobs/enr_job_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
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.

GET /v1/indices/{uid}/enrichment/suggestions Admin key

List enrichment suggestions with optional filters by status, type, and document.

Query parameters

ParameterTypeDescription
status optionalstringFilter by status: pending, applied, or dismissed.
suggestion_type optionalstringFilter by type: tags, category, attributes, search_terms, or quality.
document_id optionalstringFilter by document ID.
limit optionalnumberMaximum results to return.
Default: 50
offset optionalnumberNumber of results to skip.
Default: 0

Example

text
curl "https://search.example.com/v1/indices/products/enrichment/suggestions?status=pending&limit=20" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const result = await idx.getEnrichmentSuggestions({
  status: 'pending',
  suggestion_type: 'tags',
  limit: 20,
});

Response 200 OK

text
{
  "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

ParameterTypeDescription
id requiredstringSuggestion ID.
job_id requiredstringThe enrichment job that generated this suggestion.
document_id requiredstringThe document this suggestion applies to.
suggestion_type requiredstringOne of: tags, category, attributes, search_terms, quality.
suggestion_data requiredobjectStructured data for the suggestion. Shape depends on type (see Suggestion types below).
confidence requirednumberConfidence score between 0 and 1.
status requiredstringOne of: pending, applied, dismissed.
created_at requiredstringISO 8601 timestamp.
resolved_at requiredstring | nullISO 8601 timestamp when applied or dismissed.
POST /v1/indices/{uid}/enrichment/suggestions/{id}/apply Admin key

Apply a suggestion to the document. Merges enrichment data into the Tantivy document and re-computes embeddings.

Example

text
curl -X POST https://search.example.com/v1/indices/products/enrichment/suggestions/enr_sug_x1y2z3/apply \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
await idx.applyEnrichmentSuggestion('enr_sug_x1y2z3');

Response 200 OK

text
{
  "id": "enr_sug_x1y2z3",
  "status": "applied"
}
Note
Applying a suggestion already resolved (applied or dismissed) returns 400.
POST /v1/indices/{uid}/enrichment/suggestions/{id}/dismiss Admin key

Dismiss a suggestion without applying it.

Example

text
curl -X POST https://search.example.com/v1/indices/products/enrichment/suggestions/enr_sug_x1y2z3/dismiss \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
await idx.dismissEnrichmentSuggestion('enr_sug_x1y2z3');

Response 200 OK

text
{
  "id": "enr_sug_x1y2z3",
  "status": "dismissed"
}
POST /v1/indices/{uid}/enrichment/suggestions/batch Admin key

Batch apply or dismiss multiple suggestions at once. Maximum 100 per request.

Request body

ParameterTypeDescription
ids requiredstring[]Array of suggestion IDs to resolve. Max 100.
action requiredstringEither "applied" or "dismissed".

Example

text
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

text
const result = await idx.batchResolveEnrichmentSuggestions({
  ids: ['enr_sug_x1y2z3', 'enr_sug_a4b5c6'],
  action: 'applied',
});
console.log(result.resolved); // 2

Response 200 OK

text
{
  "resolved": 2
}
Note
When 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.

text
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

ParameterTypeDescription
enabled requiredbooleanWhether enrichment is active for this index.
provider requiredobjectLLM provider configuration (see below).
mode optionalstring"suggest" (default) or "auto_apply". See Modes below.
Default: "suggest"
confidence_threshold optionalnumberMinimum confidence for auto-apply mode (0.0 to 1.0).
Default: 0.8
batch_size optionalnumberDefault number of documents per enrichment run.
Default: 100
categories optionalstring[]Valid category names for category inference. If provided, the LLM will only suggest from this list.

Provider settings

ParameterTypeDescription
base_url requiredstringBase URL of the OpenAI-compatible API (e.g. https://api.openai.com/v1).
api_key requiredstringAPI key for the LLM provider. Stored securely, redacted in GET responses.
model requiredstringModel name (e.g. gpt-4o-mini, claude-3-haiku-20240307).
max_tokens optionalnumberMaximum tokens for the LLM response.
Default: 2048
Note
Any OpenAI-compatible API works: OpenAI, Anthropic (via proxy), Azure OpenAI, Ollama, LM Studio, Together AI, etc. The provider must support JSON mode (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.

text
{ "tags": ["helix piercing", "cartilage earring", "gold jewelry"] }

Category

Suggested category for uncategorized or miscategorized products. Constrained to your category list if configured.

text
{ "category": "Earrings > Helix" }

Attributes

Extracted key-value attributes from product text (material, style, occasion, etc.).

text
{ "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.

text
{ "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.

text
{
  "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:

  1. Loads the current document from the index.
  2. Merges the enrichment data into prefixed fields (_enrichment_tags, _enrichment_category, _enrichment_attributes, _enrichment_search_terms, _enrichment_quality_score).
  3. Re-computes embeddings for the updated document.
  4. Writes the document back to the index.