Schemas

ISO 4217 code of the reported order totals.

First day with any attribution data for this site.

Days in the window with any search or chat activity.

AskAgento surface the shopper last clicked a product in.

Unix time of the click.

Order line products the shopper clicked through AskAgento.

True when the order contains a product the shopper clicked through AskAgento.

Search rules, applied in order; when a product appears in several matching rules, the earliest rule decides. Rules with no phrases or no products are ignored.

Move out-of-stock products below in-stock ones. They are not removed.

0 (ignored) to 10 (counts as much as how well a product matches the search). Omitted signals are 0.

Number of search rules stored

Compared case-insensitively, with repeated spaces collapsed.

exact: the search text equals a phrase. contains: the search text contains a phrase.

Shown first, in this order. Added to the results even when the search did not return them.

Moved above the other results when returned.

Moved to the bottom when returned.

Order total (required when status is paid).

Unix time the order was paid (defaults to now; at most ~13 months old).

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

Local installs only (POST /install from a shop the service cannot reach): the product's main image, base64-encoded. Not stored; ignored for public shops.

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.

True when the shop is local (local_domain, private_ip, dns_unresolved): it can still install in local mode with up to local_max_products products and its product images sent inline (see POST /install).

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.

Apply the shop's merchandising (see POST /merchandising). Set false when your own code reorders the results.

Null for a pinned product that the search itself did not return.

Present and true when the product was added by a pin rule.

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