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"}
)
print(response.json())
Response: 
{
  "catalogs": [
    {"id": "cat_123", "name": "Products", "item_count": 150}
  ]
}

​
POST /public/catalogs

Create a new catalog. 
response = requests.post(
    "https://catalogapi.rastro.ai/api/public/catalogs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "Products",
        "unique_id_field": "sku",
        "schema_definition": {
            "fields": [
                {"name": "sku", "type": "string"},
                {"name": "title", "type": "string"},
                {"name": "price", "type": "number"}
            ]
        }
    }
)
Request Parameters:
ParameterTypeRequiredDescription
namestringYesCatalog name
unique_id_fieldstringYesField used to identify items (e.g., sku)
schema_definitionobjectYesSchema with fields array defining field names and types
Response: 
{
  "id": "cat_123",
  "name": "Products",
  "unique_id_field": "sku"
}

​
Item Management

​
GET /public/catalogs//items

List items in a catalog. 
response = requests.get(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"page": 1, "limit": 100}
)
Query Parameters:
ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger100Items per page (max 1000)
Response: 
{
  "items": [
    {"id": "item_123", "sku": "A1", "title": "Product A", "price": 29.99}
  ],
  "total": 150,
  "page": 1
}

​
GET /public/catalogs//items/

Get a single item by ID. 
response = requests.get(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/items/{item_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
Response: 
{
  "id": "item_123",
  "sku": "A1",
  "title": "Product A",
  "price": 29.99
}

​
PUT /public/catalogs//items/

Update a single item. Only the fields you provide will be updated. 
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}
)
Request Body: Any fields to update. Response: The updated item.

​
POST /public/catalogs//items/bulk

Create or update up to 1000 items at once. 
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}
        ],
        "unique_field": "sku"
    }
)
Request Parameters:
ParameterTypeRequiredDescription
itemsarrayYesArray of item objects (max 1000)
unique_fieldstringYesField to match for upserts
Response: 
{
  "created": 10,
  "updated": 5,
  "failed": 0
}

​
Catalog Enrichment

​
POST /public/catalogs//enrich

Start an enrichment job for all items in a catalog. 
response = requests.post(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/enrich",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "prompt": "Find product specifications",
        "output_schema": [
            {"name": "price", "type": "string", "description": "Current retail price"},
            {"name": "weight", "type": "string", "description": "Product weight"}
        ],
        "speed": "slow"
    }
)
Request Parameters:
ParameterRequiredDefaultDescription
promptYes-Search prompt for web enrichment
output_schemaYes-Fields to extract: [{name, type, description}]
allowed_domainsNoanyRestrict sources to these domains
speedNo"medium""fast", "medium", or "slow"
web_searchNotrueSet false to skip web search
taxonomyNo-Taxonomy for category prediction
predict_taxonomyNofalsePredict category for each item
quality_promptNo-Prompt for quality scoring
Response: 
{
  "job_id": "job_abc123",
  "status": "running",
  "total_items": 150
}

​
GET /public/catalogs//enrich/

Poll the status of a catalog enrichment job. 
response = requests.get(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/enrich/{job_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
Response (running): 
{
  "job_id": "job_abc123",
  "status": "running",
  "total_items": 150,
  "completed_items": 45,
  "failed_items": 2
}
Response (completed): 
{
  "job_id": "job_abc123",
  "status": "completed",
  "total_items": 150,
  "completed_items": 148,
  "failed_items": 2
}
Status Values:
StatusDescription
runningJob in progress
completedJob finished
failedJob failed
cancelledJob was cancelled

​
POST /public/catalogs//enrich//cancel

Cancel a running enrichment job. 
response = requests.post(
    f"https://catalogapi.rastro.ai/api/public/catalogs/{catalog_id}/enrich/{job_id}/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
Response: 
{
  "job_id": "job_abc123",
  "status": "cancelled",
  "total_items": 150,
  "completed_items": 45,
  "failed_items": 0
}
Items enriched before cancellation keep their data.