Catalogue Overview

A catalogue groups products under one immutable processing-feature selection. You choose the work Youzu should perform for that catalogue instead of selecting a predefined preset. Catalogue administration is a server-to-server operation authenticated with x-client-key.

Start with Upload Product Data and Track Processing, then use Check Moderation Results when the catalogue includes moderation.

Choose an ingestion method

Method	Best for
Real-time Import	Sending individual products or small JSON batches as they change
API Batch Import	Automated imports from a CSV, JSON, or XML file URL
Manual Dashboard Upload	Testing and operator-managed imports

Review the Product Data Requirements before your first import.

Create a catalogue

curl -X POST https://platform.youzu.ai/api/v1/admin/catalogue \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home Collection",
    "description": "Furniture and home accessories",
    "processingFeatures": {
      "imageSearch": true,
      "semanticTextIndexing": true,
      "aiProcessing": true,
      "moderation": true,
      "deduplication": true
    },
    "languages": ["en", "fr"],
    "moderationTemplateId": "9aac11a8-e55b-491b-a8f9-11f3ac9aab20"
  }'

processingFeatures is immutable and at least one supplied value must be true. If you omit the whole object, all five features default to true. If you supply it, omitted feature keys are false, so partial objects are valid.

Feature	Processing behavior	Derived capabilities
`imageSearch`	Stores images and builds image vectors	`search.image`
`semanticTextIndexing`	Builds semantic text vectors	No text-query capability yet; `search.text` is not granted until a query API exists
`aiProcessing`	Runs AI enrichment, translation, categorization, and enables advisory merchant-flow suggestions	`enrichment`, `translation`, `categorization`, `reprocessing`, `merchant.api`
`moderation`	Runs moderation and enables review workflows	`moderation`, `review`
`deduplication`	Builds duplicate identity and relationship data	`dedup`

Every catalogue supports product ingestion, product reads, and source-property filtering. near_space_search is derived only when both imageSearch and aiProcessing are enabled. The returned capabilities array is authoritative: enable actions only for capabilities your client understands and ignore unknown strings.

Any nonempty feature combination is valid when the customer plan grants those features. For example, create a Lens-focused catalogue with image indexing only:

curl -X POST https://platform.youzu.ai/api/v1/admin/catalogue \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lens Product Images",
    "processingFeatures": {
      "imageSearch": true
    }
  }'

languages and categoryTemplateId require aiProcessing. moderationTemplateId requires moderation. Unsupported combinations are rejected rather than silently ignored.

Discover feature labels and capability mappings without authentication:

GET /api/v1/catalogue-features

This public discovery endpoint does not expose customer-specific plan grants.

Successful JSON responses use a standard envelope:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "clientId": "3f94d470-e682-4a7e-8bb6-80fb4d516399",
    "name": "Home Collection",
    "processingFeatures": {
      "imageSearch": true,
      "semanticTextIndexing": true,
      "aiProcessing": true,
      "moderation": true,
      "deduplication": true
    },
    "capabilities": ["product.ingest", "product.read", "filter.source_properties", "search.image", "enrichment", "translation", "categorization", "merchant.api", "moderation", "review", "dedup", "reprocessing", "near_space_search"],
    "provisioningStatus": "ready",
    "enabled": true,
    "languages": ["en", "fr"]
  }
}

Catalogue responses contain customer-facing settings only. Infrastructure connections, credentials, cluster information, and internal database identifiers are never returned.

Manage and scope catalogues

Method	Path	Purpose
`GET`	`/api/v1/admin/catalogue`	List all your catalogues
`POST`	`/api/v1/admin/catalogue`	Create a catalogue
`GET`	`/api/v1/admin/catalogue/{id}`	Get one catalogue
`DELETE`	`/api/v1/admin/catalogue/{id}`	Delete a catalogue
`POST`	`/api/v1/admin/catalogue/{id}/ingest`	Ingest into an explicit catalogue

Every request uses x-client-key. Youzu derives the customer from the key and verifies ownership of each path catalogue. Use explicit catalogue IDs when an account has multiple catalogues. The catalogue-free ingest route and tokens without catalogueId work only when exactly one enabled compatible catalogue can be resolved; otherwise the request is rejected as ambiguous.

Languages contain between one and five unique supported codes and always include en when aiProcessing is enabled. Supported codes are en, de, fr, es, it, nl, pt, ru, uk, pl, cs, sk, hu, ro, bg, hr, sl, sr, zh, ja, ko, el, az, and ar.

The public API currently supports create, read, and delete operations. It does not expose a processing-feature update route because the selection is immutable.

Errors

Errors preserve the relevant HTTP status:

{
  "success": false,
  "error": "Validation failed",
  "details": {}
}

Expect 400 for malformed input or an invalid feature combination, 401 for a missing or invalid key, 403 when the plan does not grant a selected feature, 404 for an unknown catalogue or template, 409 for an unsupported action, ambiguous catalogue scope, or another state conflict, and 422 for input that cannot be applied. A downstream transport failure is returned as 502; when a downstream service responds with another 5xx status, the facade preserves that exact status.

2D to 3D

Merchant API