Catalogs Quickstart

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.

unique_id_field is a required legacy compatibility field on public catalog creation. Keep the actual business key, such as sku, in your schema and item data.

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())

curl -X POST "https://catalogapi.rastro.ai/api/public/catalogs/cat_abc123/items/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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}
    ]
  }'

const response = await fetch(`https://catalogapi.rastro.ai/api/public/catalogs/${catalogId}/items/bulk`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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 }
    ]
  })
});
console.log(await response.json());

Response:

{
  "success": true,
  "items_processed": 3,
  "items_created": 3,
  "items_failed": 0,
  "schema_evolved": false
}

There is no unique_field query parameter. Put your business key fields, such as sku, directly in each item object.

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())

curl "https://catalogapi.rastro.ai/api/public/catalogs/cat_abc123/items" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(`https://catalogapi.rastro.ai/api/public/catalogs/${catalogId}/items`, {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
console.log(await 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())

curl -X PUT "https://catalogapi.rastro.ai/api/public/catalogs/cat_abc123/items/item_1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price": 24.99}'

const response = await fetch(`https://catalogapi.rastro.ai/api/public/catalogs/${catalogId}/items/${itemId}`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ price: 24.99 })
});
console.log(await 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

Getting Started

Enrich API

Flows

Catalogs

Photo Studio

Complete API Reference

MCP (Codex / Claude)

Enterprise

Catalogs Quickstart

1. Create a catalog

2. Add items (bulk)

3. List your items

4. Update an item

5. Configure your catalog

Key Concepts

What’s Next

API Reference

Examples

MCP Quickstart

​1. Create a catalog

​2. Add items (bulk)

​3. List your items

​4. Update an item

​5. Configure your catalog

​Key Concepts

​What’s Next

API Reference

Examples

MCP Quickstart

1. Create a catalog

2. Add items (bulk)

3. List your items

4. Update an item

5. Configure your catalog

Key Concepts

What’s Next