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.

Words that mean the same in this shop. They are added to the search text of /search (text, voice, text + image), the chatbot and agents, and widen /suggest.

Searches that open a page instead of showing results. /search answers a text or voice search matching one with redirect and no results (a redirected text search is not counted against limits.searches); /suggest lists the redirect while typing.

Compared case-insensitively, with repeated spaces collapsed.

Absolute http(s) URL to open.

exact: the search text equals a phrase. contains: the search text contains a phrase as whole words.

Text shown for the redirect in autocomplete (defaults to the phrase).

Number of search rules stored

Number of synonym groups stored

Number of search redirects 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.

false: any term finds the others. true: the first term also finds the later ones, but not the other way round (e.g. [hoodie, sweatshirt]).

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, GET /suggest, 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.

Voice query: base64-encoded WAV (16-bit PCM, mono, 8–48 kHz, ≤15 s). A leading data:audio/...;base64, prefix is stripped if present. Costs 100 searches.

Spoken language for voice (e.g. en-US, de-DE, de_DE, fr). Default en-US.

Omit to infer from the body: text only → text, image_base64 only → image, both present → both, audio_base64 only → voice. 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.

The query as matched (trimmed, lower-cased).

Popular searches that continue the typed text (most frequent first); for an empty q, the trending searches of the last 7 days.

Echoed text query when modality is text or both; the transcript for voice

Voice only. Recognized speech that was searched (may be empty).

Voice only. Spoken language used for recognition (e.g. en-US).

Voice only. Searches debited for this request (100).

Present when the shop redirects this text or voice search to a page; results is then empty. Open redirect.url instead of showing results.

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

Optional. The product page the shopper is asking from (AI Assistant). Its synced details (price, attributes, variants, description) are given to the assistant, so questions like "is it waterproof?" are answered about that product. Ignored when the product is not in the last catalogue sync.

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