Catalog Upload

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:

string

required

Unique product identifier (Stock Keeping Unit). Used as the primary key — uploading the same SKU again updates the existing product.

string

required

Product name. This is the most important field for search quality.

string

Category hierarchy, e.g. "Dairy > Milk > UHT Milk". Improves search context.

string

Brand name. Customers frequently search by brand.

string

Product description. Included in the embedding for semantic search.

string

Ingredients list. Enables the AI to answer “what’s in this product?” questions.

string

Country of origin.

string

default:"pcs"

Unit of measure: "pcs", "kg", "l", etc.

number

Minimum increment for quantity changes (e.g., 0.1 for items sold by weight).

number

Minimum order quantity.

number

Product weight in grams.

number

Product volume in milliliters.

string

URL to the product image. Displayed in product cards within the chat.

object

Arbitrary key-value metadata stored as JSON.

string

Product barcode (EAN/UPC).

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.

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

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.

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

string

Unique job identifier.

string

Current status: pending, embedding, complete, or failed.

number

Total number of products in the upload.

number

Number of products that have been embedded so far. Use this with total to show progress.

number

Number of new products created.

number

Number of existing products updated (content fields changed).

number

Number of products that were identical to the existing version (no re-embedding needed).

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:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (1-200, default: 50)
`category`	string	Filter by category path (partial match)
`brand`	string	Filter by brand (partial match)
`search`	string	Text search in name and brand
`is_active`	boolean	Filter 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

Batch size recommendations

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.

Smart change detection

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.

Embedding batching

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.

Automated sync patterns

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.

Getting Started

Integration Guides

Widget SDK

Webhooks

Concepts

Product Data Format

Content Fields

Bulk Upload

Job Status Fields

Partial Updates (PATCH)

Soft Delete

Force Reindex

List Products

List Jobs

Tips for Large Catalogs

​Product Data Format

​Content Fields

​Bulk Upload

​Job Status Fields

​Partial Updates (PATCH)

​Soft Delete

​Force Reindex

​List Products

​List Jobs

​Tips for Large Catalogs

Product Data Format

Content Fields

Bulk Upload

Job Status Fields

Partial Updates (PATCH)

Soft Delete

Force Reindex

List Products

List Jobs

Tips for Large Catalogs