> ## Documentation Index > Fetch the complete documentation index at: https://docs.rastro.ai/llms.txt > Use this file to discover all available pages before exploring further. # Enrich Data > 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`. ## OpenAPI ````yaml /api-reference/openapi.json post /public/enrich openapi: 3.1.0 info: title: Rastro Public API description: >- Public API for enrichment, catalog management, workflows, activities, snapshots, taxonomy, and MCP integrations. version: 0.1.0 servers: - url: https://catalogapi.rastro.ai/api security: - bearerAuth: [] paths: /public/enrich: post: tags: - Enrich summary: Enrich Data description: >- 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`. operationId: enrich_data_api_public_enrich_post parameters: - name: X-Organization-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Organization-Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EnrichRequest' examples: direct: summary: Direct enrichment value: items: - part_number: 6205-2RS name: Deep Groove Ball Bearing output_schema: - name: bore_diameter type: string description: Inner diameter in mm - name: outer_diameter type: string description: Outer diameter in mm speed: fast catalog: summary: Use a catalog configuration value: catalog_id: cat_123 items: - sku: A1 speed: deep multipart/form-data: schema: type: object required: - request_json properties: request_json: type: string description: >- JSON-encoded EnrichRequest. For large jobs with items_file, omit inline items from request_json. items_file: type: string format: binary description: >- Optional JSON upload containing either an array of items or an object with an items array. Use exactly one items_file for large jobs. knowledge_base_files: type: array items: type: string format: binary description: >- Optional knowledge-base documents used for retrieval/citations during enrichment. knowledge_base_metadata_json: type: string description: >- Optional JSON metadata for knowledge_base_files, keyed by file name or upload index. additionalProperties: false responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EnrichResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - bearerAuth: [] components: schemas: EnrichRequest: additionalProperties: false description: Request to enrich item data. properties: prompt: anyOf: - type: string - type: 'null' default: '' description: >- Search prompt for web enrichment (e.g., 'Find product specifications'). Optional - defaults to empty string. title: Prompt items: description: >- List of items to enrich. Required unless source_activity_id or source_catalog_id is provided. items: additionalProperties: true type: object title: Items type: array output_schema: description: >- Schema defining fields to extract. Required unless source_activity_id or source_catalog_id is provided. items: $ref: '#/components/schemas/FieldDefinition' title: Output Schema type: array attribute_sets: anyOf: - additionalProperties: items: additionalProperties: true type: object type: array type: object - type: 'null' default: null description: >- 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. title: Attribute Sets source_hint_sets: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: >- 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. title: Source Hint Sets allowed_domains: anyOf: - items: type: string type: array - type: 'null' default: null description: Restrict web scraping to these domains only title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' default: null description: Domains to exclude from web search and URL fetches title: Blocked Domains speed: default: deep description: >- Processing speed: 'fast' (quick), 'medium' (balanced), 'deep'/'slow' (thorough default), 'ultra_slow' (maximum reasoning / strongest model path) title: Speed type: string web_search: default: true description: >- If true (default), performs web search to gather content. If false, skips web search and uses input data directly for extraction/validation. title: Web Search type: boolean max_rows: anyOf: - type: integer - type: 'null' default: null description: >- Limit processing to first N items. All items are stored. Use source_activity_id to process remaining items later. title: Max Rows taxonomy: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: Taxonomy definition for category prediction (TaxonomyInput format) title: Taxonomy predict_taxonomy: default: false description: If true and taxonomy is provided, predict category_id for each item title: Predict Taxonomy type: boolean predict_taxonomy_attributes: default: true description: >- If true, also predict taxonomy_attributes after classification. Set false for taxonomy classification only. title: Predict Taxonomy Attributes type: boolean validate_semantics: default: false description: >- If true, AI validates that field values make sense given their descriptions (e.g., email field contains valid email format) title: Validate Semantics type: boolean review_mode: default: true description: >- Run the enrich review agent after enrichment, apply clear output corrections, and attach activity.output.audit decisions. Public enrichment jobs keep this enabled. title: Review Mode type: boolean audit_decisions_enabled: default: true description: >- When false, the post-enrichment audit still applies clear output corrections but suppresses human-facing audit decisions/suggestions. title: Audit Decisions Enabled type: boolean include_source_explanations: default: true description: >- Include source_explanation for each enriched field (and taxonomy attribute) explaining how the value was derived from sources. Always enabled. title: Include Source Explanations type: boolean low_confidence: anyOf: - $ref: '#/components/schemas/LowConfidenceConfig' - type: 'null' default: null description: >- Optional add-on for returning low-confidence candidates at the end of each result catalog_id: anyOf: - type: string - type: 'null' default: null description: Optional catalog ID to link this enrichment job to title: Catalog Id template_id: anyOf: - type: string - type: 'null' default: null description: >- Optional organization-scoped enrichment template key. Template extraction fields apply to omitted request fields; template-owned safety controls remain enforced. title: Template Id async_mode: default: false description: >- If true, returns immediately with job_id instead of waiting for results title: Async Mode type: boolean staged_status: default: pending description: >- Status for staged changes: 'pending' (default, visible to admin) or 'draft' (vendor draft, not visible to admin until submitted) title: Staged Status type: string source_activity_id: anyOf: - type: string - type: 'null' default: null description: >- Activity ID of a previous run. Processes all stored items using saved config. title: Source Activity Id source_catalog_id: anyOf: - type: string - type: 'null' default: null description: >- Catalog UUID to read items FROM as the enrichment input. Independent of catalog_id (the write target). title: Source Catalog Id file_name: anyOf: - type: string - type: 'null' default: null description: Original file name if items were loaded from a file title: File Name include_service_usage: default: false description: >- If true, include detailed service_usage metrics (costs, tokens, per-item stats) in response title: Include Service Usage type: boolean include_debug_log: default: false description: >- If true, capture full audit log per item (raw markdown, tool history, LLM responses) and upload to storage title: Include Debug Log type: boolean capture_source_artifacts: default: false description: >- If true, preserve durable copies of consulted source material for audit trails. Web pages are captured as screenshots; PDFs are copied as PDF files. title: Capture Source Artifacts type: boolean reextract_from_activity_id: anyOf: - type: string - type: 'null' default: null description: >- Activity ID to re-extract from. Skips web gather, reuses stored web research data. Supports prompt/schema overrides and feedback. title: Reextract From Activity Id global_feedback: anyOf: - type: string - type: 'null' default: null description: >- Feedback to apply to all items during re-extraction (appended to prompt) title: Global Feedback item_feedback: anyOf: - additionalProperties: type: string type: object - type: 'null' default: null description: >- Per-item feedback keyed by row index as string (e.g. {'0': 'Wrong product', '3': 'Price is in EUR not USD'}) title: Item Feedback source_row_indices: anyOf: - items: type: integer type: array - type: 'null' default: null description: >- Row indices to re-extract (others carried forward from source). Only used with reextract_from_activity_id. title: Source Row Indices webhook_url: anyOf: - type: string - type: 'null' default: null description: HTTPS URL to POST results to when job completes. Must use https://. title: Webhook Url knowledge_base_enabled: default: false description: >- If true, use an uploaded knowledge base (OpenAI vector store) for structured generation. title: Knowledge Base Enabled type: boolean knowledge_base_vector_store_id: anyOf: - type: string - type: 'null' default: null description: OpenAI vector store ID containing uploaded knowledge base files. title: Knowledge Base Vector Store Id knowledge_base_sources: anyOf: - additionalProperties: type: string type: object - type: 'null' default: null description: >- Optional SOURCE_X -> source URL mapping used for field-level citations (for example {'SOURCE_1': 'https://.../specs.pdf'}). title: Knowledge Base Sources knowledge_base_metadata: anyOf: - additionalProperties: additionalProperties: true type: object type: object - type: 'null' default: null description: >- Optional SOURCE_X -> metadata mapping for uploaded knowledge-base files (for example {'SOURCE_1': {'doc_type': 'approved_marketing'}}). title: Knowledge Base Metadata host_media: default: false description: >- If true, upload all media URLs (images, PDFs) found in enrichment results to hosted storage, replacing with hosted URLs. title: Host Media type: boolean strict_hosted_media: default: false description: >- If true, media/document output fields are cleared unless the URL is successfully copied to hosted storage. title: Strict Hosted Media type: boolean image_processing: anyOf: - $ref: '#/components/schemas/ImageProcessingConfig' - type: 'null' default: null description: >- Optional deterministic post-processing for hosted images, such as square white-background catalog normalization. title: EnrichRequest type: object EnrichResponse: properties: job_id: anyOf: - type: string - type: 'null' title: Job Id description: >- Job ID for tracking (always returned). Use this with source_activity_id to trigger full run. results: items: $ref: '#/components/schemas/EnrichItemResult' type: array title: Results description: Enrichment results for each item (empty if async_mode=true) total_items: type: integer title: Total Items description: Number of items being processed (may be limited by max_rows) total_rows: anyOf: - type: integer - type: 'null' title: Total Rows description: Total items passed in the request (before max_rows limit) successful: type: integer title: Successful description: Number of successfully enriched items default: 0 credits_used: type: integer title: Credits Used description: Number of credits used (1 per successful item) default: 0 status: type: string title: Status description: 'Job status: ''running'' (async) or ''completed'' (sync)' default: completed service_usage: anyOf: - additionalProperties: true type: object - type: 'null' title: Service Usage description: >- Detailed API usage metrics (costs, calls, tokens) - only present when job is complete pricing_estimates: anyOf: - additionalProperties: true type: object - type: 'null' title: Pricing Estimates description: >- Estimated pricing breakdown (for example knowledge-base storage + model runtime costs when available) knowledge_base_enabled: anyOf: - type: boolean - type: 'null' title: Knowledge Base Enabled description: Whether this enrichment job used a knowledge base vector store knowledge_base_sources: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Knowledge Base Sources description: >- SOURCE_X -> hosted document URL mapping for knowledge-base files used by the activity page: anyOf: - type: integer - type: 'null' title: Page description: Current page number (1-indexed) page_size: anyOf: - type: integer - type: 'null' title: Page Size description: Number of results per page total_pages: anyOf: - type: integer - type: 'null' title: Total Pages description: Total number of pages available completed_items: anyOf: - type: integer - type: 'null' title: Completed Items description: >- Number of items with results available so far (useful while status=running) type: object required: - total_items title: EnrichResponse description: Response with enriched data for all items. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError FieldDefinition: description: >- Definition for a single field to extract - matches attribute mapper field schema. properties: name: description: Field name title: Name type: string type: default: string description: 'Field type: string, number, integer, boolean, array' title: Type type: string description: description: Description of what to extract for this field title: Description type: string array_element_type: anyOf: - type: string - type: 'null' default: null description: >- For array fields, the type of elements: string, number, integer, image_url title: Array Element Type unit: anyOf: - type: string - type: 'null' default: null description: Units for numeric fields (e.g., 'kg', 'USD', 'cm') title: Unit enum: anyOf: - items: type: string type: array - type: 'null' default: null description: Constrain extraction to these specific values title: Enum items_enum: anyOf: - items: type: string type: array - type: 'null' default: null description: For array fields, constrain items to these specific values title: Items Enum sample_values: anyOf: - items: type: string type: array - type: 'null' default: null description: Example values to guide extraction title: Sample Values required: anyOf: - type: boolean - type: 'null' default: null description: Whether the field is required title: Required merge: anyOf: - type: boolean - type: 'null' default: null description: Whether to merge with existing values title: Merge pattern: anyOf: - type: string - type: 'null' default: null description: Optional regex pattern constraint for extracted text title: Pattern pattern_message: anyOf: - type: string - type: 'null' default: null description: Human-readable guidance for the pattern constraint title: Pattern Message min_length: anyOf: - type: integer - type: 'null' default: null description: Minimum string length title: Min Length max_length: anyOf: - type: integer - type: 'null' default: null description: Maximum string length title: Max Length minimum: anyOf: - type: number - type: 'null' default: null description: Minimum numeric value title: Minimum maximum: anyOf: - type: number - type: 'null' default: null description: Maximum numeric value title: Maximum unique: anyOf: - type: boolean - type: 'null' default: null description: Whether the field should be unique within the target catalog title: Unique semantic_type: anyOf: - type: string - type: 'null' default: null description: Optional semantic type hint such as image_url or document_url title: Semantic Type required: - name - description title: FieldDefinition type: object LowConfidenceConfig: description: >- Optional request flag for emitting low-confidence candidates at the end of a result. properties: enabled: default: false description: If true, return low-confidence candidates alongside canonical output title: Enabled type: boolean scopes: description: Which candidate families to include items: type: string title: Scopes type: array placement: default: tail description: >- Payload placement for low-confidence candidates. Only tail is currently supported title: Placement type: string max_candidates_per_item: default: 8 description: Maximum low-confidence candidates to return per item maximum: 20 minimum: 1 title: Max Candidates Per Item type: integer title: LowConfidenceConfig type: object ImageProcessingConfig: description: Optional deterministic post-processing applied when media is hosted. properties: enabled: default: false description: Whether to normalize hosted image assets. title: Enabled type: boolean make_square: default: true description: Pad image onto a square canvas. title: Make Square type: boolean background_color: default: '#FFFFFF' description: Hex background color used for padding/transparency. title: Background Color type: string min_side_px: default: 500 description: Minimum output side length. maximum: 8192 minimum: 1 title: Min Side Px type: integer max_side_px: default: 1700 description: Maximum output side length. maximum: 8192 minimum: 1 title: Max Side Px type: integer output_format: default: jpeg description: 'Output format: jpeg, png, or webp.' title: Output Format type: string quality: default: 92 description: Output quality for lossy formats. maximum: 100 minimum: 1 title: Quality type: integer force_reprocess_hosted: default: false description: Re-download and normalize already-hosted catalog images. title: Force Reprocess Hosted type: boolean fields: anyOf: - items: type: string type: array - type: 'null' default: null description: >- Optional field allow-list. If omitted, all detected image fields are processed. title: Fields title: ImageProcessingConfig type: object EnrichItemResult: properties: original_data: additionalProperties: true type: object title: Original Data description: The original input data after_data: additionalProperties: true type: object title: After Data description: >- Complete enriched record with values, sources, and source_explanations all_sources: items: type: string type: array title: All Sources description: All web sources used across all fields error: anyOf: - type: string - type: 'null' title: Error description: Error message if enrichment failed for this item category_id: anyOf: - type: string - type: 'null' title: Category Id description: Predicted taxonomy node ID taxonomy_attributes: anyOf: - additionalProperties: true type: object - type: 'null' title: Taxonomy Attributes description: Predicted taxonomy-specific attributes taxonomy_attribute_sources: anyOf: - additionalProperties: items: type: string type: array type: object - type: 'null' title: Taxonomy Attribute Sources description: >- Per-attribute source URLs or input references used to derive taxonomy attribute values taxonomy_attribute_explanations: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Taxonomy Attribute Explanations description: Per-attribute explanations of how values were derived from sources review_info: anyOf: - additionalProperties: true type: object - type: 'null' title: Review Info description: AI reasoning, flags for human review low_confidence_candidates: anyOf: - items: $ref: '#/components/schemas/LowConfidenceCandidate' type: array - type: 'null' title: Low Confidence Candidates description: >- Optional tail section of plausible but non-canonical field or taxonomy candidates low_confidence_fields: anyOf: - items: type: string type: array - type: 'null' title: Low Confidence Fields description: >- Field or taxonomy attribute names that should be highlighted as low-confidence while remaining in after_data staged_change_id: anyOf: - type: string - type: 'null' title: Staged Change Id description: ID of the staged change record (if stage_changes=true) type: object required: - original_data title: EnrichItemResult description: Result for a single enriched item. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError LowConfidenceCandidate: properties: scope: type: string title: Scope description: 'Candidate scope: field, taxonomy_attribute, or category' default: field name: type: string title: Name description: Canonical field or taxonomy attribute name candidate_value: anyOf: - type: string - type: 'null' title: Candidate Value description: Candidate value serialized as exact text or compact JSON confidence: type: string title: Confidence description: Confidence level for this candidate default: LOW reason: anyOf: - type: string - type: 'null' title: Reason description: >- Why this candidate is plausible but not strong enough for canonical output sources: items: type: string type: array title: Sources description: Resolved source URLs or input:* references supporting the candidate source_explanation: anyOf: - type: string - type: 'null' title: Source Explanation description: Optional short explanation of where the candidate came from type: object required: - name title: LowConfidenceCandidate description: >- A plausible but non-canonical candidate that should not be merged into final output. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Rastro API key or user token ````