---
title: "Enrich Data"
method: POST
path: "/public/enrich"
tags: ["Enrich"]
---

# Enrich Data

`POST /public/enrich`

## Request

- Base URL: `https://catalogapi.rastro.ai/api`
- URL: `https://catalogapi.rastro.ai/api/public/enrich`
- Auth: HTTP bearer

Enrich items using web research, with optional taxonomy prediction.

Accepts both `application/json` (plain JSON body) and `multipart/form-data`
(with `request_json` field, optional `items_file`, and optional
`knowledge_base_files`).

**Two modes of operation:**

1. **Direct mode**: Pass items and output_schema directly
2. **Full-run mode**: Pass `source_activity_id` from a previous run to process all stored items

**Example: Direct enrichment**
```json
{
  "prompt": "Find product specifications",
  "items": [{"name": "iPhone 15 Pro"}],
  "output_schema": [
    {"name": "price", "type": "string", "description": "Current retail price"},
    {"name": "weight", "type": "string", "description": "Product weight"}
  ]
}
```

**Example: Dry run (process first 10 items)**
```json
{
  "prompt": "Find product specifications",
  "items": [... all 1000 items ...],
  "output_schema": [...],
  "max_rows": 10
}
```

**Example: Full run from previous activity**
```json
{
  "prompt": "Find product specifications",
  "source_activity_id": "abc123-previous-activity-id"
}
```

**Large jobs:** send multipart/form-data with a small `request_json` and
one `items_file` JSON upload. `items_file` must be a JSON array, or an
object with an `items` array. Do not send `items_storage_url`; it is internal.

All items are stored in the activity, so full runs can be triggered later using `source_activity_id`.

## Headers

- `X-Organization-Id` string, nullable

## Request body

- EnrichRequest: Request to enrich item data.
  - `prompt` string, nullable: Search prompt for web enrichment (e.g., 'Find product specifications'). Optional - defaults to empty string.
  - `items` object[]: List of items to enrich. Required unless source_activity_id or source_catalog_id is provided.
  - `output_schema` FieldDefinition[]: Schema defining fields to extract. Required unless source_activity_id or source_catalog_id is provided.
    - `name` string, required: Field name
    - `type` string: Field type: string, number, integer, boolean, array
    - `description` string, required: Description of what to extract for this field
    - `array_element_type` string, nullable: For array fields, the type of elements: string, number, integer, image_url
    - `unit` string, nullable: Units for numeric fields (e.g., 'kg', 'USD', 'cm')
    - `enum` string[], nullable: Constrain extraction to these specific values
    - `items_enum` string[], nullable: For array fields, constrain items to these specific values
    - `sample_values` string[], nullable: Example values to guide extraction
    - `required` boolean, nullable: Whether the field is required
    - `merge` boolean, nullable: Whether to merge with existing values
    - `pattern` string, nullable: Optional regex pattern constraint for extracted text
    - `pattern_message` string, nullable: Human-readable guidance for the pattern constraint
    - `min_length` integer, nullable: Minimum string length
    - `max_length` integer, nullable: Maximum string length
    - `minimum` number, nullable: Minimum numeric value
    - `maximum` number, nullable: Maximum numeric value
    - `unique` boolean, nullable: Whether the field should be unique within the target catalog
    - `semantic_type` string, nullable: Optional semantic type hint such as image_url or document_url
  - `attribute_sets` object, nullable: Canonical registry for requested-attribute jobs. Items carry attribute_set_id; workers expand that id to requested_attributes only at runtime. Per-row requested_attributes payloads are rejected by the public endpoint.
  - `source_hint_sets` object, nullable: Canonical registry for repeated per-item source hints. Items carry source_hint_set_id; workers expand that id to source_hints only at runtime. Inline source_hints are rejected by the public endpoint.
  - `allowed_domains` string[], nullable: Restrict web scraping to these domains only
  - `blocked_domains` string[], nullable: Domains to exclude from web search and URL fetches
  - `speed` string: Processing speed: 'fast' (quick), 'medium' (balanced), 'deep'/'slow' (thorough default), 'ultra_slow' (maximum reasoning / strongest model path)
  - `web_search` boolean: If true (default), performs web search to gather content. If false, skips web search and uses input data directly for extraction/validation.
  - `max_rows` integer, nullable: Limit processing to first N items. All items are stored. Use source_activity_id to process remaining items later.
  - `taxonomy` object, nullable: Taxonomy definition for category prediction (TaxonomyInput format)
  - `predict_taxonomy` boolean: If true and taxonomy is provided, predict category_id for each item
  - `predict_taxonomy_attributes` boolean: If true, also predict taxonomy_attributes after classification. Set false for taxonomy classification only.
  - `validate_semantics` boolean: If true, AI validates that field values make sense given their descriptions (e.g., email field contains valid email format)
  - `review_mode` boolean: Run the enrich review agent after enrichment, apply clear output corrections, and attach activity.output.audit decisions. Public enrichment jobs keep this enabled.
  - `audit_decisions_enabled` boolean: When false, the post-enrichment audit still applies clear output corrections but suppresses human-facing audit decisions/suggestions.
  - `include_source_explanations` boolean: Include source_explanation for each enriched field (and taxonomy attribute) explaining how the value was derived from sources. Always enabled.
  - `low_confidence` LowConfidenceConfig: Optional request flag for emitting low-confidence candidates at the end of a result.
    - `enabled` boolean: If true, return low-confidence candidates alongside canonical output
    - `scopes` string[]: Which candidate families to include
    - `placement` string: Payload placement for low-confidence candidates. Only tail is currently supported
    - `max_candidates_per_item` integer: Maximum low-confidence candidates to return per item
  - `catalog_id` string, nullable: Optional catalog ID to link this enrichment job to
  - `template_id` string, nullable: Optional organization-scoped enrichment template key. Template extraction fields apply to omitted request fields; template-owned safety controls remain enforced.
  - `async_mode` boolean: If true, returns immediately with job_id instead of waiting for results
  - `staged_status` string: Status for staged changes: 'pending' (default, visible to admin) or 'draft' (vendor draft, not visible to admin until submitted)
  - `source_activity_id` string, nullable: Activity ID of a previous run. Processes all stored items using saved config.
  - `source_catalog_id` string, nullable: Catalog UUID to read items FROM as the enrichment input. Independent of catalog_id (the write target).
  - `file_name` string, nullable: Original file name if items were loaded from a file
  - `include_service_usage` boolean: If true, include detailed service_usage metrics (costs, tokens, per-item stats) in response
  - `include_debug_log` boolean: If true, capture full audit log per item (raw markdown, tool history, LLM responses) and upload to storage
  - `capture_source_artifacts` boolean: If true, preserve durable copies of consulted source material for audit trails. Web pages are captured as screenshots; PDFs are copied as PDF files.
  - `reextract_from_activity_id` string, nullable: Activity ID to re-extract from. Skips web gather, reuses stored web research data. Supports prompt/schema overrides and feedback.
  - `global_feedback` string, nullable: Feedback to apply to all items during re-extraction (appended to prompt)
  - `item_feedback` object, nullable: Per-item feedback keyed by row index as string (e.g. {'0': 'Wrong product', '3': 'Price is in EUR not USD'})
  - `source_row_indices` integer[], nullable: Row indices to re-extract (others carried forward from source). Only used with reextract_from_activity_id.
  - `webhook_url` string, nullable: HTTPS URL to POST results to when job completes. Must use https://.
  - `knowledge_base_enabled` boolean: If true, use an uploaded knowledge base (OpenAI vector store) for structured generation.
  - `knowledge_base_vector_store_id` string, nullable: OpenAI vector store ID containing uploaded knowledge base files.
  - `knowledge_base_sources` object, nullable: Optional SOURCE_X -> source URL mapping used for field-level citations (for example {'SOURCE_1': 'https://.../specs.pdf'}).
  - `knowledge_base_metadata` object, nullable: Optional SOURCE_X -> metadata mapping for uploaded knowledge-base files (for example {'SOURCE_1': {'doc_type': 'approved_marketing'}}).
  - `host_media` boolean: If true, upload all media URLs (images, PDFs) found in enrichment results to hosted storage, replacing with hosted URLs.
  - `strict_hosted_media` boolean: If true, media/document output fields are cleared unless the URL is successfully copied to hosted storage.
  - `image_processing` ImageProcessingConfig: Optional deterministic post-processing applied when media is hosted.
    - `enabled` boolean: Whether to normalize hosted image assets.
    - `make_square` boolean: Pad image onto a square canvas.
    - `background_color` string: Hex background color used for padding/transparency.
    - `min_side_px` integer: Minimum output side length.
    - `max_side_px` integer: Maximum output side length.
    - `output_format` string: Output format: jpeg, png, or webp.
    - `quality` integer: Output quality for lossy formats.
    - `force_reprocess_hosted` boolean: Re-download and normalize already-hosted catalog images.
    - `fields` string[], nullable: Optional field allow-list. If omitted, all detected image fields are processed.

## Response `200`

Successful Response

- EnrichResponse: Response with enriched data for all items.
  - `job_id` string, nullable: Job ID for tracking (always returned). Use this with source_activity_id to trigger full run.
  - `results` EnrichItemResult[]: Enrichment results for each item (empty if async_mode=true)
    - `original_data` object, required: The original input data
    - `after_data` object: Complete enriched record with values, sources, and source_explanations
    - `all_sources` string[]: All web sources used across all fields
    - `error` string, nullable: Error message if enrichment failed for this item
    - `category_id` string, nullable: Predicted taxonomy node ID
    - `taxonomy_attributes` object, nullable: Predicted taxonomy-specific attributes
    - `taxonomy_attribute_sources` object, nullable: Per-attribute source URLs or input references used to derive taxonomy attribute values
    - `taxonomy_attribute_explanations` object, nullable: Per-attribute explanations of how values were derived from sources
    - `review_info` object, nullable: AI reasoning, flags for human review
    - `low_confidence_candidates` LowConfidenceCandidate[], nullable: Optional tail section of plausible but non-canonical field or taxonomy candidates
      - `scope` string: Candidate scope: field, taxonomy_attribute, or category
      - `name` string, required: Canonical field or taxonomy attribute name
      - `candidate_value` string, nullable: Candidate value serialized as exact text or compact JSON
      - `confidence` string: Confidence level for this candidate
      - `reason` string, nullable: Why this candidate is plausible but not strong enough for canonical output
      - `sources` string[]: Resolved source URLs or input:* references supporting the candidate
      - `source_explanation` string, nullable: Optional short explanation of where the candidate came from
    - `low_confidence_fields` string[], nullable: Field or taxonomy attribute names that should be highlighted as low-confidence while remaining in after_data
    - `staged_change_id` string, nullable: ID of the staged change record (if stage_changes=true)
  - `total_items` integer, required: Number of items being processed (may be limited by max_rows)
  - `total_rows` integer, nullable: Total items passed in the request (before max_rows limit)
  - `successful` integer: Number of successfully enriched items
  - `credits_used` integer: Number of credits used (1 per successful item)
  - `status` string: Job status: 'running' (async) or 'completed' (sync)
  - `service_usage` object, nullable: Detailed API usage metrics (costs, calls, tokens) - only present when job is complete
  - `pricing_estimates` object, nullable: Estimated pricing breakdown (for example knowledge-base storage + model runtime costs when available)
  - `knowledge_base_enabled` boolean, nullable: Whether this enrichment job used a knowledge base vector store
  - `knowledge_base_sources` object, nullable: SOURCE_X -> hosted document URL mapping for knowledge-base files used by the activity
  - `page` integer, nullable: Current page number (1-indexed)
  - `page_size` integer, nullable: Number of results per page
  - `total_pages` integer, nullable: Total number of pages available
  - `completed_items` integer, nullable: Number of items with results available so far (useful while status=running)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/rastro-ai/apis/rastro-public-api.md) - [All operations](https://skmtc.dev/rastro-ai/apis/rastro-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rastro-ai/apis/rastro-public-api/revisions/57c8ed4854bb?raw)