Skip to main content
VIZOCHOK stores your product catalog for AI search and recommendations. Prices and stock availability are not stored here — those come from your backend via webhooks at query time. The catalog API requires a secret API key (sk_...) with catalog scope.

​
Product Data Format

Each product is described by the ProductInput schema:
​
sku
string
required
Unique product identifier (Stock Keeping Unit). Used as the primary key — uploading the same SKU again updates the existing product.
​
name
string
required
Product name. This is the most important field for search quality.
​
category_path
string
Category hierarchy, e.g. "Dairy > Milk > UHT Milk". Improves search context.
​
brand
string
Brand name. Customers frequently search by brand.
​
description
string
Product description. Included in the embedding for semantic search.
​
ingredients
string
Ingredients list. Enables the AI to answer “what’s in this product?” questions.
​
country
string
Country of origin.
​
unit
string
default:"pcs"
Unit of measure: "pcs", "kg", "l", etc.
​
quantity_step
number
Minimum increment for quantity changes (e.g., 0.1 for items sold by weight).
​
min_quantity
number
Minimum order quantity.
​
weight
number
Product weight in grams.
​
volume
number
Product volume in milliliters.
​
image_url
string
URL to the product image. Displayed in product cards within the chat.
​
attributes
object
Arbitrary key-value metadata stored as JSON.
​
barcode
string
Product barcode (EAN/UPC).
​
is_active
boolean
default:true
Set to false to soft-delete a product from search results.

​
Content Fields

The following fields are combined into an enriched text and used for embedding generation: name, description, ingredients, brand, category_path, country. Changing any of these triggers re-embedding of the product.

​
Bulk Upload

Upload products using PUT /api/v1/catalog/products. This endpoint performs an upsert — new products are created, existing products (matched by sku) are updated.
1

Prepare your JSON payload

{
  "products": [
    {
      "sku": "milk-001",
      "name": "Молоко Lactel 2.5% 1л",
      "brand": "Lactel",
      "category_path": "Молочні продукти > Молоко",
      "description": "Ультрапастеризоване молоко 2.5% жирності",
      "ingredients": "Молоко коров'яче нормалізоване",
      "unit": "pcs",
      "weight": 1000,
      "image_url": "https://your-cdn.com/milk-001.jpg",
      "country": "Україна"
    },
    {
      "sku": "bread-042",
      "name": "Хліб Київхліб Столичний 950г",
      "brand": "Київхліб",
      "category_path": "Хліб та випічка > Хліб",
      "unit": "pcs",
      "weight": 950
    }
  ]
}
2

Upload via API

curl -X PUT https://api.vizochok.com/api/v1/catalog/products \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d @products.json
Response (202 Accepted):
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "accepted",
  "total": 2,
  "to_embed": 2,
  "unchanged": 0
}
Product metadata is saved to the database immediately. Embedding generation runs in the background. Products are searchable once their embeddings are complete.
3

Poll for job completion

curl https://api.vizochok.com/api/v1/catalog/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_your_secret_key"
Response:
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "your-tenant-id",
  "status": "embedding",
  "total": 2,
  "embedded": 1,
  "created": 2,
  "updated": 0,
  "unchanged": 0,
  "errors": [],
  "started_at": "2026-03-18T10:30:00Z",
  "completed_at": null
}
Job statuses: pending -> embedding -> complete (or failed).

​
Job Status Fields

​
job_id
string
Unique job identifier.
​
status
string
Current status: pending, embedding, complete, or failed.
​
total
number
Total number of products in the upload.
​
embedded
number
Number of products that have been embedded so far. Use this with total to show progress.
​
created
number
Number of new products created.
​
updated
number
Number of existing products updated (content fields changed).
​
unchanged
number
Number of products that were identical to the existing version (no re-embedding needed).
​
errors
string[]
List of error messages for individual products that failed.

​
Partial Updates (PATCH)

Update individual product fields without re-uploading the entire catalog: 
curl -X PATCH https://api.vizochok.com/api/v1/catalog/products/milk-001 \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ультрапастеризоване молоко 2.5% жирності. Без лактози.",
    "image_url": "https://your-cdn.com/milk-001-v2.jpg"
  }'
Response: 
{
  "sku": "milk-001",
  "updated_fields": ["description", "image_url"],
  "re_embedded": true
}
Only content fields (name, description, ingredients, brand, category_path, country) trigger re-embedding. Changing non-content fields like image_url, weight, or unit updates metadata instantly without re-embedding.

​
Soft Delete

Deactivate a product (removes it from search results but keeps the data): 
curl -X DELETE https://api.vizochok.com/api/v1/catalog/products/milk-001 \
  -H "Authorization: Bearer sk_your_secret_key"
Returns 204 No Content on success. To reactivate, PATCH with "is_active": true.

​
Force Reindex

Trigger a full re-embedding of all active products. Use this after changing your embedding model or if search quality seems degraded: 
curl -X POST https://api.vizochok.com/api/v1/catalog/reindex \
  -H "Authorization: Bearer sk_your_secret_key"
Response: 
{
  "status": "started",
  "product_count": 1500
}
Reindexing re-embeds every active product. For large catalogs, this may take several minutes and will consume embedding API credits.

​
List Products

Browse your uploaded catalog with pagination and filtering: 
curl "https://api.vizochok.com/api/v1/catalog/products?page=1&limit=50&brand=Lactel" \
  -H "Authorization: Bearer sk_your_secret_key"
Supported query parameters:
ParameterTypeDescription
pageintegerPage number (default: 1)
limitintegerItems per page (1-200, default: 50)
categorystringFilter by category path (partial match)
brandstringFilter by brand (partial match)
searchstringText search in name and brand
is_activebooleanFilter by active status

​
List Jobs

View recent catalog upload jobs: 
curl https://api.vizochok.com/api/v1/catalog/jobs \
  -H "Authorization: Bearer sk_your_secret_key"
Returns up to 50 most recent jobs, sorted by most recent first. Job data is stored in Redis with a 24-hour TTL.

​
Tips for Large Catalogs

The API accepts any number of products in a single request, but for catalogs over 5,000 products we recommend splitting into batches of 1,000-2,000. This gives you more granular progress tracking and reduces the risk of timeouts.
VIZOCHOK computes an MD5 hash of each product’s content fields and compares it with the existing record. Products with identical content are skipped entirely — no re-embedding occurs. This makes repeated full catalog syncs efficient.
Embeddings are generated in batches of 50 products. For a 10,000-product catalog, this means 200 embedding API calls. The process runs in the background and does not block your API request.
Set up a daily cron job or webhook from your PIM/ERP to push the full catalog:
# Example: nightly catalog sync
0 3 * * * curl -X PUT https://api.vizochok.com/api/v1/catalog/products \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d @/path/to/catalog-export.json
Thanks to smart change detection, only modified products are re-embedded.