Skip to main content

​
Catalog Management

​
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())
Query Parameters:
ParameterTypeDefaultDescription
limitinteger10Items per page (1–100)
offsetinteger0Number 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."
    }
)
Request Parameters:
ParameterTypeRequiredDescription
namestringNoNew catalog name (1–100 chars)
descriptionstringNoUpdated description
auto_evolve_schemabooleanNoAllow automatic schema evolution
strict_modebooleanNoReject unknown fields
catalog_mdstringNoMarkdown 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"
    }
)
Request Parameters:
ParameterTypeRequiredDescription
field_namestringYesName of the field
field_typestringYesType: string, number, boolean, array, object
descriptionstringNoField description
requiredbooleanNoWhether the field is required (default: false)
field_categorystringNoinput or generated (default: input)
unitstringNoUnit of measurement (e.g., kg, V, W)
sample_valuesarrayNoExample values for the field
validation_rulesobjectNoJSON 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"
    }
)
Request Parameters:
ParameterTypeRequiredDescription
fields_to_addarrayNoFields to add (same shape as POST schema/fields)
fields_to_updatearrayNoFields to update (include field_name + changed attributes)
fields_to_removearrayNoField names to remove
reasonstringNoReason 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"]}
                ]
            }
        }
    }
)
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"}
)
Query Parameters:
ParameterTypeDefaultDescription
limitinteger50Items per page (1–1000)
offsetinteger0Number of items to skip
searchstring—Text search across all fields
sortstring—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.

​
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. Matching is based on the catalog’s configured unique ID field. 
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}
        ]
    }
)
Request Parameters:
ParameterTypeRequiredDescription
itemsarrayYesArray of item objects (max 1000)
source_infoobjectNoMetadata about the data source
auto_evolve_schemabooleanNoOverride catalog’s auto_evolve_schema setting
Item matching for upserts uses the catalog’s configured unique ID field — you do not need to specify a unique_field parameter. Configure the unique ID field when creating the catalog.
Response: 
{
  "success": true,
  "items_processed": 15,
  "items_created": 10,
  "items_failed": 0,
  "schema_evolved": false,
  "errors": []
}

​
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": "slow"
    }
)
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
  • GET /public/catalogs/{catalog_id}/activities to audit pending/completed activities
  • POST /public/catalogs/{catalog_id}/activities to create activity shells
  • 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
See MCP Reference for full workflow guidance.