Schemas

set stores the merchant key; clear removes BYOK credentials from the install record.

Required when action=set.

Merchant LLM API key. Required when action=set. Never logged by the API.

Optional model id for action=set (e.g. gpt-5-mini for OpenAI, or an OpenRouter model id). When omitted, the chatbot uses the server default (OpenRouter ids are prefixed with openai/ when needed).

True when a BYOK key is stored after this request; false after clear.

Present when byok is true (the provider just stored).

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).

Shop host name, e.g. shop.example.com. A full URL is also accepted.

URL of one product image, picked at random from the catalogue about to be installed. Products are indexed by their images, so a catalogue without one cannot be installed: omitting it yields blocked (no_product_images).

True only when verdict is pass.

Machine-readable outcome, e.g. reachable, local_domain, private_ip, dns_unresolved, tls_invalid, password_protected, image_forbidden, image_not_found, no_product_images, rate_limited, timeout.

Sentence suitable for display to the shop administrator.

Per-check detail, in the order the checks ran.

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; send it in X-Askagento-Site-Id on every authenticated call.

Secret key; accepted on every authenticated route. Keep it on your server and never expose it in a web page.

Public key; accepted only on POST /chatbot, POST /search and POST /mcp. Safe to embed in storefront pages and AI agent configs.

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

Search text, at least 2 characters

Base64-encoded image bytes. A leading data:image/...;base64, prefix is stripped if present. Never fetched over the network.

Omit to infer from the body: text only → text, image_base64 only → image, both present → both. Setting both requires text (≥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 (free, basic, pro); null if no plan is set

Human-readable plan label

Remaining AI token quota

Remaining search quota

Plan slug; null if no plan is set

Remaining monthly plan allowance for this site; null if no limits are tracked. Reset to the tier maximum each billing period. Does not include add-on packs.

Unspent one-time add-on pack credits, omitted keys meaning zero; null when the site has none. These do not expire and are only spent once limits reaches zero, so the site's true remaining balance is limits + pack_units.

Tier-level maximums for the current plan; null if no plan is set. Includes a products field (how many products the plan indexes) in addition to tokens/searches.

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

Number of products the service indexes on the current plan; null if no plan is set.

True when the catalogue is larger than the current plan indexes. While true, catalogue-backed endpoints return 403 (code: product_limit_exceeded) until the catalogue is covered by a larger plan or reduced in size.

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