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

# Catalogs Quickstart

> Store and manage your product data

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](https://dashboard.rastro.ai), or via the API:

```python theme={null}
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.

<Note>
  `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.
</Note>

## 2. Add items (bulk)

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```bash cURL theme={null}
  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}
      ]
    }'
  ```

  ```typescript TypeScript theme={null}
  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());
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "items_processed": 3,
  "items_created": 3,
  "items_failed": 0,
  "schema_evolved": false
}
```

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

## 3. List your items

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(
      f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl "https://catalogapi.rastro.ai/api/public/catalogs/cat_abc123/items" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`https://catalogapi.rastro.ai/api/public/catalogs/${catalogId}/items`, {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  });
  console.log(await response.json());
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```bash cURL theme={null}
  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}'
  ```

  ```typescript TypeScript theme={null}
  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());
  ```
</CodeGroup>

## 5. Configure your catalog

Update catalog settings, schema, taxonomy, and context:

```python theme={null}
# 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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/catalogs/reference">
    All endpoints and parameters
  </Card>

  <Card title="Examples" icon="code" href="/catalogs/examples">
    Full CRUD and enrichment examples
  </Card>

  <Card title="MCP Quickstart" icon="robot" href="/mcp/quickstart">
    Agent-driven bulk edits with staged review
  </Card>
</CardGroup>