Catalog & public IDs

Your instance's catalog — the products and materials customers can visualise — is managed with your Viewa contact and read through the catalog endpoints.

Prefixed public IDs

Every object the API exposes has a stable public ID with a type prefix:

IDs are opaque — don't parse them beyond the prefix, and don't assume any ordering. Raw database IDs never appear in the API.

Products, materials, and material sets

A product is a configurable window treatment (a roller blind, a drape, a shutter). Each product exposes one or more material slots — the parts of the product a customer can choose a finish for. The materials valid for a slot are grouped into material sets. See Slot tokens for how slots are addressed.

Agent-friendly encoding

GET /products and GET /products/{ref}/materials can return the same list envelope as TOON, a compact tabular encoding that costs roughly a third to a half fewer tokens than JSON when an AI agent re-reads the catalog every turn. Ask for it with the Accept header:

curl "$BASE_URL/products" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: text/toon"

The response is text/toon; charset=utf-8 and decodes to exactly the JSON { data, pagination } envelope — it is an encoding, not a different schema. JSON stays the default for any other Accept value, single-resource endpoints are JSON only, and errors are always application/problem+json.

Products with styles and API-only products

Some products in the Viewa visualiser publish styles — several pre-authored looks (an S-wave drape, a pinch-pleat drape) selected inside a single product. That is a visualiser affordance, and those products are not published on the API: they never appear in GET /products, can't be fetched by ID or SKU, can't be aliased, and are rejected by the render endpoint like any unknown product.

If a product you need is missing for this reason, ask your Viewa contact to model each look as its own flat product. A product intended only for integrators can be marked API only, which publishes it here while keeping it out of the visualiser — so your catalog and the visualiser's can differ deliberately.

Because of this, styles on a product detail response is always an empty array and stylesLabel is always null in v1. styleOptions is unrelated and is populated as normal — it is the product's own configuration vocabulary.

Child instances

If your account has child instances (for example, per-brand or per-region stores), a child reads its parent's catalog narrowed to its configured subset. Products outside the subset are absent from responses entirely, exactly as if they didn't exist.

Referring to catalog objects

Endpoints that take a catalog reference accept either the Viewa public ID or, if you've registered them, your own identifiers — see SKU aliasing.