Catalogs API Reference

Catalog Management

POST /public/catalogs

Create a catalog with an initial JSON Schema.

response = requests.post(
    "https://catalogapi.rastro.ai/api/public/catalogs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "Products",
        "description": "Main product catalog",
        "unique_id_field": "sku",
        "product_id_field": "product_id",
        "auto_evolve_schema": True,
        "strict_mode": False,
        "schema_definition": {
            "properties": {
                "sku": {"type": "string", "description": "Stock keeping unit"},
                "title": {"type": "string", "description": "Product title"},
                "price": {"type": "number", "description": "Product price"}
            },
            "required": ["sku"]
        }
    }
)

curl -X POST "https://catalogapi.rastro.ai/api/public/catalogs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Products",
    "unique_id_field": "sku",
    "schema_definition": {
      "properties": {
        "sku": {"type": "string"},
        "title": {"type": "string"}
      },
      "required": ["sku"]
    }
  }'

Request Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Catalog name (1-100 chars)
`description`	string	No	Optional description
`unique_id_field`	string	Yes	Legacy compatibility field required by the public create request. Include the intended business key, such as `sku`, in your schema and item data; this request field is not a separate runtime selector
`product_id_field`	string	No	Field used to group variants under products
`auto_evolve_schema`	boolean	No	Allow automatic schema evolution
`strict_mode`	boolean	No	Reject unknown fields
`schema_definition`	object	Yes	Initial JSON Schema with `properties` and optional `required`
`validation_rules`	object	No	Catalog-level validation rules
`catalog_md`	string	No	Markdown context for enrichment/mapping prompts
`master_catalog_id`	string	No	Master catalog to inherit defaults from
`use_master_catalog_defaults`	boolean	No	Whether to inherit defaults from the org default master catalog

Response: The created catalog object.

GET /public/catalogs

List all catalogs in your account.

response = requests.get(
    "https://catalogapi.rastro.ai/api/public/catalogs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 50, "offset": 0}
)
print(response.json())

curl "https://catalogapi.rastro.ai/api/public/catalogs?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	10	Items per page (1–100)
`offset`	integer	0	Number of items to skip

Response:

{
  "catalogs": [
    {
      "id": "cat_123",
      "name": "Products",
      "description": "Main product catalog",
      "auto_evolve_schema": true,
      "strict_mode": false,
      "item_count": 150,
      "current_schema_version": "1.0",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total_count": 1,
  "page": 1,
  "page_size": 50
}

GET /public/catalogs/

Get details of a specific catalog. Response: Same shape as a single catalog object from the list endpoint.

PUT /public/catalogs/

Update catalog settings. Only provided fields are changed; omitted fields remain unchanged.

response = requests.put(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "Renamed Catalog",
        "description": "Updated description",
        "auto_evolve_schema": False,
        "catalog_md": "# Catalog Context\nThis catalog contains industrial bearings."
    }
)

curl -X PUT "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Catalog", "description": "Updated description"}'

Request Parameters:

Parameter	Type	Required	Description
`name`	string	No	New catalog name (1–100 chars)
`description`	string	No	Updated description
`auto_evolve_schema`	boolean	No	Allow automatic schema evolution
`strict_mode`	boolean	No	Reject unknown fields
`catalog_md`	string	No	Markdown context injected into enrichment/mapping prompts

Response: The updated catalog object.

DELETE /public/catalogs/

Delete a catalog and all its data (items, schema, snapshots).

curl -X DELETE "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{"message": "Catalog cat_123 deleted successfully"}

Schema Management

GET /public/catalogs//schema

Get the current schema definition, including field metadata and workflow tracking.

curl "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "version": "1.2",
  "schema_definition": {
    "properties": {
      "sku": {"type": "string", "description": "Stock keeping unit"},
      "price": {"type": "number", "description": "Product price"}
    },
    "required": ["sku"]
  },
  "total_fields": 2,
  "input_fields_count": 1,
  "generated_fields_count": 1,
  "fields_workflow_info": [...]
}

POST /public/catalogs//schema/fields

Add a new field to the catalog schema. Creates a new schema version.

response = 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",
        "required": False,
        "field_category": "input",
        "unit": "kg"
    }
)

curl -X POST "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/schema/fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "weight_kg", "field_type": "number", "description": "Product weight"}'

Request Parameters:

Parameter	Type	Required	Description
`field_name`	string	Yes	Name of the field
`field_type`	string	Yes	Type such as `string`, `number`, `integer`, `boolean`, `array`, or `object`
`description`	string	No	Field description
`required`	boolean	No	Whether the field is required (default: false)
`field_category`	string	No	`input` or `generated`. Stored as workflow-tracking metadata when `workflow_id` is provided
`position`	string	No	Where to add the field: `top` or `bottom`
`workflow_id`	string	No	Workflow ID associated with the schema change
`unit`	string	No	Unit of measurement (e.g., `kg`, `V`, `W`)
`sample_values`	array	No	Example values for the field
`validation_rules`	object	No	JSON Schema validation (pattern, enum, etc.)

Response:

{
  "success": true,
  "catalog_id": "cat_123",
  "new_schema_version": "1.3",
  "previous_schema_version": "1.2",
  "fields_added": ["weight_kg"],
  "message": "Field 'weight_kg' added successfully. New schema version: 1.3"
}

PUT /public/catalogs//schema/fields/batch

Add, update, and/or remove multiple fields in one atomic operation.

response = requests.put(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/schema/fields/batch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "fields_to_add": [
            {"field_name": "color", "field_type": "string", "description": "Product color"},
            {"field_name": "weight", "field_type": "number", "unit": "kg"}
        ],
        "fields_to_update": [
            {"field_name": "price", "description": "Updated price description"}
        ],
        "fields_to_remove": ["old_field"],
        "reason": "Schema cleanup"
    }
)

curl -X PUT "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/schema/fields/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields_to_add": [{"field_name": "color", "field_type": "string"}],
    "fields_to_remove": ["old_field"],
    "reason": "Schema cleanup"
  }'

Request Parameters:

Parameter	Type	Required	Description
`fields_to_add`	array	No	Fields to add (same shape as POST schema/fields)
`fields_to_update`	array	No	Fields to update (include `field_name` + changed attributes)
`fields_to_remove`	array	No	Field names to remove
`reason`	string	No	Reason for the changes

Response: Same shape as POST schema/fields response.

Taxonomy Management

GET /public/catalogs//taxonomy

Get the catalog’s taxonomy with computed inheritance (levels, paths, inherited attributes). Returns null if no taxonomy is configured.

curl "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/taxonomy" \
  -H "Authorization: Bearer YOUR_API_KEY"

Supports ETag caching via If-None-Match header — returns 304 Not Modified when unchanged.

PUT /public/catalogs//taxonomy

Set or replace the catalog taxonomy. Creates a new schema version.

response = 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": {
            "electronics": {
                "name": "Electronics",
                "parent": None,
                "attributes": []
            },
            "phones": {
                "name": "Phones",
                "parent": "electronics",
                "attributes": [
                    {"name": "brand", "type": "enum", "values": ["Apple", "Samsung"]}
                ]
            }
        }
    }
)

curl -X PUT "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/taxonomy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Categories",
    "hierarchy_levels": ["Category"],
    "nodes": {
      "electronics": {"name": "Electronics", "parent": null, "attributes": []}
    }
  }'

Response: The enriched taxonomy with computed fields (level, path, children, inherited_attributes).

DELETE /public/catalogs//taxonomy

Remove taxonomy from the catalog. Creates a new schema version without taxonomy.

curl -X DELETE "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/taxonomy" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 204 No Content

Catalog Context

GET /public/catalogs//catalog-md

Get the catalog’s markdown context (injected into enrichment and mapping prompts).

curl "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/catalog-md" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{"catalog_id": "cat_123", "catalog_md": "# Product Context\nThis catalog contains..."}

PUT /public/catalogs//catalog-md

Update the catalog’s markdown context directly (versioned).

curl -X PUT "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/catalog-md" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog_md": "# Updated Context\nNew instructions for enrichment."}'

You can also update catalog_md via PUT /public/catalogs/{catalog_id} by including the catalog_md field in the request body.

GET /public/catalogs//quality-prompt

Get the catalog’s quality prompt (used by the judge and readiness checks).

PUT /public/catalogs//quality-prompt

Set the quality prompt.

{"prompt": "Rate completeness of product specs on a 1-5 scale..."}

Item Management

GET /public/catalogs//items

List items in a catalog with pagination, search, and sorting.

response = requests.get(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 50, "offset": 0, "sort": "created_at:desc"}
)

curl "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Items per page (1–1000)
`offset`	integer	0	Number of items to skip
`search`	string	—	Text search across all fields
`search_query`	string	—	Alias for `search`
`sort`	string	—	Sort by `field:direction` (e.g., `created_at:desc`)

Response:

{
  "items": [
    {
      "id": "item_123",
      "data": {"title": "Product A", "price": 29.99, "variants": [...]},
      "metadata": {"created_at": "2026-01-15T10:30:00Z", "updated_at": null, "version": null}
    }
  ],
  "total": 150,
  "page": 0,
  "limit": 50
}

GET /public/catalogs//items/

Get a single item by database ID. Response: Single item in the same shape as list items.

POST /public/catalogs//items

Upsert a single item. Put the business identifier inside data (for example, {"sku": "A1"}); the legacy unique_identifier field is still required by the request shape but is not used as a separate selector.

curl -X POST "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_identifier": "A1",
    "data": {"sku": "A1", "title": "Product A", "price": 29.99},
    "source_info": {"source": "public_api"}
  }'

Parameter	Type	Required	Description
`unique_identifier`	string	Yes	Legacy compatibility field. Send the same value as the identifier inside `data`
`data`	object	Yes	Item data to write
`source_info`	object	No	Metadata recorded with the write

Response: The created or updated item.

PUT /public/catalogs//items/

Update a single item. Only the fields you provide will be updated. Request Body: Any fields to update (dynamic schema). Response: The updated item.

DELETE /public/catalogs//items/

Delete a single item. Response:

{"message": "Item deleted successfully"}

POST /public/catalogs//items/bulk

Create or update up to 1000 items at once. Include your business key fields, such as sku, in each item object.

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}
        ]
    }
)

curl -X POST "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"sku": "A1", "title": "Product A", "price": 29.99}]}'

Request Parameters:

Parameter	Type	Required	Description
`items`	array	Yes	Array of item objects (max 1000)
`source_info`	object	No	Metadata about the data source
`auto_evolve_schema`	boolean	No	Accepted for compatibility. Public bulk writes currently allow schema evolution from the submitted item data

There is no unique_field query parameter. Put the business key fields directly in each item object.

Response:

{
  "success": true,
  "items_processed": 15,
  "items_created": 10,
  "items_failed": 0,
  "schema_evolved": false,
  "errors": []
}

Product Variant Management

Use these endpoints when a catalog groups variants under a product item. The {product_id} path parameter is the parent product item’s database ID, not the business product_id field value stored in row data.

POST /public/catalogs//products//items

Create one variant under a product.

curl -X POST "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/products/{product_item_id}/items" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SHIRT-001-RED-M","color":"Red","size":"M","price":29.99}'

PUT /public/catalogs//products/

Update product-level fields shared by variants.

curl -X PUT "https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/products/{product_item_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_title":"Classic T-Shirt","product_brand":"MyBrand"}'

POST /public/catalogs//products//items/bulk

Bulk upsert variants for one product.

{
  "product": {
    "product_title": "Classic T-Shirt",
    "product_brand": "MyBrand"
  },
  "variants": [
    {"sku": "SHIRT-001-RED-M", "color": "Red", "size": "M"},
    {"sku": "SHIRT-001-BLUE-M", "color": "Blue", "size": "M"}
  ],
  "source_info": {"source": "public_api"},
  "auto_evolve_schema": true
}

Response:

{
  "product_id": "SHIRT-001",
  "items_processed": 2,
  "items_created": 2,
  "items_updated": 0,
  "items_failed": 0,
  "schema_evolved": false,
  "errors": [],
  "warnings": []
}

Enriching Catalog Items

To enrich items in a catalog, use the Enrich API with the catalog_id parameter. The catalog’s schema and taxonomy are automatically applied.

response = requests.post(
    "https://catalogapi.rastro.ai/api/public/enrich",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "catalog_id": "cat_abc123",
        "items": [
            {"part_number": "6205-2RS", "name": "Deep Groove Ball Bearing"}
        ],
        "speed": "deep"
    }
)

See Enrich Examples for more details.

Snapshots

GET /public/catalogs//snapshots

List catalog snapshots.

POST /public/catalogs//snapshots

Create a snapshot. Request body: {"reason": "Before migration"}.

POST /public/catalogs//snapshots//restore

Restore from a snapshot. Automatically creates a safety snapshot first.

MCP-Oriented Endpoints

These endpoints are commonly used by Rastro MCP servers for large catalog workflows:

GET /public/catalogs/{catalog_id}/raw-items for full-fidelity catalog row pulls. Supports limit (1-5000, default 1000), offset, entity_type=product|variant, search, sort_field, and sort_order=asc|desc
GET /public/catalogs/{catalog_id}/raw-items/{item_id} for a single raw catalog row
GET /public/catalogs/{catalog_id}/activities to audit pending/completed activities
POST /public/catalogs/{catalog_id}/activities to create activity shells
POST /public/catalogs/{catalog_id}/activities/custom-transform to create a custom transform activity
POST /public/catalogs/{catalog_id}/activities/{activity_id}/save-workflow to save an activity as a workflow
POST /public/activities/{activity_id}/staged-changes/append to append staged changes in chunks
POST /public/activities/{activity_id}/pending-review to finalize one review activity

Activity listing supports status, type, limit, and offset query parameters. Snapshots support snapshot_type, limit, and offset. See MCP Reference for full workflow guidance.

​Catalog Management

​POST /public/catalogs

​GET /public/catalogs

​GET /public/catalogs/

​PUT /public/catalogs/

​DELETE /public/catalogs/

​Schema Management

​GET /public/catalogs//schema

​POST /public/catalogs//schema/fields

​PUT /public/catalogs//schema/fields/batch

​Taxonomy Management

​GET /public/catalogs//taxonomy

​PUT /public/catalogs//taxonomy

​DELETE /public/catalogs//taxonomy

​Catalog Context

​GET /public/catalogs//catalog-md

​PUT /public/catalogs//catalog-md

​GET /public/catalogs//quality-prompt

​PUT /public/catalogs//quality-prompt

​Item Management

​GET /public/catalogs//items

​GET /public/catalogs//items/

​POST /public/catalogs//items

​PUT /public/catalogs//items/

​DELETE /public/catalogs//items/

​POST /public/catalogs//items/bulk

​Product Variant Management

​POST /public/catalogs//products//items

​PUT /public/catalogs//products/

​POST /public/catalogs//products//items/bulk

​Enriching Catalog Items

​Snapshots

​GET /public/catalogs//snapshots

​POST /public/catalogs//snapshots

​POST /public/catalogs//snapshots//restore

​MCP-Oriented Endpoints

Catalog Management

POST /public/catalogs

GET /public/catalogs

GET /public/catalogs/

PUT /public/catalogs/

DELETE /public/catalogs/

Schema Management

GET /public/catalogs//schema

POST /public/catalogs//schema/fields

PUT /public/catalogs//schema/fields/batch

Taxonomy Management

GET /public/catalogs//taxonomy

PUT /public/catalogs//taxonomy

DELETE /public/catalogs//taxonomy

Catalog Context

GET /public/catalogs//catalog-md

PUT /public/catalogs//catalog-md

GET /public/catalogs//quality-prompt

PUT /public/catalogs//quality-prompt

Item Management

GET /public/catalogs//items

GET /public/catalogs//items/

POST /public/catalogs//items

PUT /public/catalogs//items/

DELETE /public/catalogs//items/

POST /public/catalogs//items/bulk

Product Variant Management

POST /public/catalogs//products//items

PUT /public/catalogs//products/

POST /public/catalogs//products//items/bulk

Enriching Catalog Items

Snapshots

GET /public/catalogs//snapshots

POST /public/catalogs//snapshots

POST /public/catalogs//snapshots//restore

MCP-Oriented Endpoints