Skip to main content
Catalogs store your product data in Rastro. Create a catalog, add items, then enrich them with Flows or the Enrich API.

​
1. Create a catalog

Create a catalog in the Rastro dashboard, or via the API: 
response = requests.post(
    "https://catalogapi.rastro.ai/api/public/catalogs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "My Products",
        "description": "Product catalog",
        "unique_id_field": "sku",
        "auto_evolve_schema": True,
        "schema_definition": {
            "properties": {
                "sku": {"type": "string", "description": "Stock keeping unit"},
                "title": {"type": "string", "description": "Product name"},
                "price": {"type": "number", "description": "Price"}
            },
            "required": ["sku"]
        }
    }
)
catalog_id = response.json()["id"]
Once created, copy your catalog_id to use in API calls below.

​
2. Add items (bulk)

response = requests.post(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items/bulk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "items": [
            {"sku": "A1", "title": "Product A", "price": 29.99},
            {"sku": "A2", "title": "Product B", "price": 39.99},
            {"sku": "A3", "title": "Product C", "price": 49.99}
        ]
    }
)
print(response.json())
Response: 
{
  "success": true,
  "items_processed": 3,
  "items_created": 3,
  "items_failed": 0,
  "schema_evolved": false
}
Item matching for upserts uses the catalog’s configured unique ID field (e.g., sku). You don’t need to pass a unique_field parameter — it’s set once when the catalog is created.

​
3. List your items

response = requests.get(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response.json())
Response: 
{
  "items": [
    {"id": "item_1", "data": {"title": "Product A", "price": 29.99, ...}, "metadata": {...}},
    {"id": "item_2", "data": {"title": "Product B", "price": 39.99, ...}, "metadata": {...}}
  ],
  "total": 3,
  "page": 0,
  "limit": 50
}

​
4. Update an item

response = requests.put(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items/{item_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"price": 24.99}
)
print(response.json())

​
5. Configure your catalog

Update catalog settings, schema, taxonomy, and context: 
# Update catalog settings and context
requests.put(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "catalog_md": "# Catalog Context\nThis catalog contains industrial bearings.",
        "auto_evolve_schema": True
    }
)

# Add a field to the schema
requests.post(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/schema/fields",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "field_name": "weight_kg",
        "field_type": "number",
        "description": "Product weight in kilograms",
        "unit": "kg"
    }
)

# Set a taxonomy for categorization
requests.put(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/taxonomy",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "Product Categories",
        "hierarchy_levels": ["Category", "Subcategory"],
        "nodes": {
            "bearings": {"name": "Bearings", "parent": None, "attributes": []},
            "ball_bearings": {"name": "Ball Bearings", "parent": "bearings", "attributes": [
                {"name": "bore_diameter", "type": "number", "unit": "mm"}
            ]}
        }
    }
)

​
Key Concepts

  • Schema — Defines the structure of your catalog items. Fields can be added/updated/removed via the API.
  • Taxonomy — Optional hierarchical category tree with per-category attributes. Used for enrichment and classification.
  • Catalog MD — Markdown context injected into enrichment and mapping prompts to guide AI behavior.
  • Bulk upsert — Add up to 1000 items at once. Items are matched by the catalog’s unique ID field.
  • Catalogs + Flows — Connect a catalog to a Flow to automatically enrich items when they’re added.

​
What’s Next

API Reference

All endpoints and parameters

Examples

Full CRUD and enrichment examples

MCP Quickstart

Agent-driven bulk edits with staged review