Schemas

Effective price (sale price when on sale, otherwise regular price).

HTML-formatted price string (may include <span> tags).

Product publication status (e.g. publish, draft, private).

True when the merchant has marked the product as featured.

True when a sale price is active.

Canonical product page URL.

Product categories; each item is a WooCommerce term object.

Product tags; each item is a WooCommerce term object.

Product variation objects (variable products only).

Product creation timestamp (used by get_featured_products new_arrivals sort).

Alias for date_created (plugin may send either field).

Alias for date_modified (plugin may send either field).

woocommerce — full catalogue with image + text data. knowledge_base — text-only Confluence/article chunks for askagento.com chat.

Optional IPv4 string for the shop host (plugin may send DNS resolution result).

True when the catalogue hash changed on this sync (re-embed required). Unchanged-hash syncs do not clear a previously true flag.

New site identifier; store with api_key for subsequent calls.

Install-time secret; required on all routes except POST /install (new installs) and OPTIONS preflights.

ISO 8601 timestamp (UTC) with Z suffix

Map of source product id to cross-sell targets (similarity-ranked)

Map of source product id (string) to ranked neighbor list

Hybrid score; lower is better when present

hybrid, image, or text

Text query (alias q)

Alias for query

Base64 image; data URLs are accepted

Omit for automatic modality: text if only query/q, image if only image_base64, both if query and image are present. both requires query (≥2 chars) and image_base64.

Echoed text query when modality is text or both

chat — full conversation; last user turn drives product retrieval (see POST /chatbot). health — connectivity probe; messages optional and ignored; max_completion_tokens ignored.

Required when action=chat (non-empty after normalization); omitted or ignored for health. Up to 24 turns; each content truncated to 12 000 chars.

Alias max_tokens also accepted; capped at 4096. Ignored when action=health (server uses 3).

Round-trip latency to the chat provider in milliseconds

Text reply from the model

Number of catalogue products injected as context for action=chat; always 0 for health

Remaining token quota for the site after this call; null if no quota is set

HTTP status code returned by the upstream chat API

One of: initialize, notifications/initialized, tools/call, tools/list

Request id (omit for notifications)

For tools/call: {"name": "chat_with_shop"|"get_catalogue_stats"|"get_featured_products"|"get_product_by_id"|"get_shop_status"|"get_similar_products"|"list_categories"|"list_tags"|"search_products", "arguments": {...}}

Plan slug (e.g. starter, growth); null if no plan is set

Human-readable plan label

True while the site is on the install-time free trial of its plan

ISO-8601 UTC timestamp when the trial ends; null when not on a trial.

Remaining AI token quota

Remaining search quota

Plan slug; null if no plan is set

True while the site is on the install-time free trial of its plan

ISO-8601 UTC timestamp when the trial ends; null when not on a trial.

Current remaining limits for this site; null if no limits are tracked

Tier-level maximums for the current plan; null if no plan is set. Includes a products field (the plan's product cap) in addition to tokens/searches.

Number of products in the shop's catalogue; null if not yet recorded

Maximum products allowed on the current plan; null if no plan is set

True when the catalogue exceeds the plan's product cap. While true, AI features are blocked until the merchant upgrades or reduces the catalogue.

Alias for action; supply either action or filter_action.

Alias for canonical_attributes when generating attribute filters.

HTTP status from the upstream chat API when the failure was from the LLM