Askagento API

MCP 2024-11-05 over HTTP. Every request is a JSON-RPC 2.0 POST.

Supported methods:

• initialize — server capabilities and protocol version.
• notifications/initialized — acknowledged silently (empty 200 body).
• tools/call — execute a tool (see tool list below).
• tools/list — catalogue of available tools.

tools/call tools (alphabetical):

• chat_with_shop — conversational shop assistant (message, optional history); delegates to POST /chatbot with action=chat (product retrieval + LLM). Debits limits.tokens like /chatbot.
• get_catalogue_stats — orientation summary: total and published product count, price range, number of distinct categories and tags, featured and on-sale counts (no arguments). Reads the stored S3 catalogue; no quota debit.
• get_featured_products — curated product list: list_type one of featured (merchant-starred), on_sale (active discounts), or new_arrivals (sorted by date_created descending); limit 1–50 (default 12). Reads the stored S3 catalogue; no quota debit.
• get_product_by_id — full detail for one product by numeric product_id: title, URL, image, price, categories, tags, description (up to 400 chars). Reads the stored S3 catalogue; no quota debit.
• get_shop_status — install status, plan, and remaining usage quotas (no arguments).
• get_similar_products — cross-sell and/or upsell neighbors for one product_id (optional recommendation_type, limit). Reads the same precomputed similarity bundle as /recommend/* (install-time catalogue similarity index, no LLM); no quota debit.
• list_categories — all product categories in the catalogue with name, slug, and product count. No quota debit.
• list_tags — all product tags in the catalogue with name, slug, and product count. No quota debit.
• search_products — semantic search by text, image, or both (text and/or image_base64, optional modality, limit); debits limits.searches when tracked.

Successful tool calls and protocol errors (initialize, unknown method, etc.) return HTTP 200 with a JSON-RPC 2.0 body. Auth and site lookup failures also use HTTP 200 with JSON-RPC error objects (codes -32001 unauthorized, -32004 site not found) so MCP clients can always parse the envelope. HTTP 400 is reserved for a non-JSON or non-JSON-RPC request body at the transport layer.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> can be the public key or the secret key; use the public key in browser code and AI agent configs.

Sends a conversation to a configured chat model.

action=chat — The last user message drives semantic product search against the site's catalogue (up to 12 matches). Matching products are injected as a system message before the LLM request. Retrieval does not debit limits.searches. If search or catalogue load fails, the chat continues without product context.

action=health — Minimal connectivity check: messages is ignored, completion is capped at 3 tokens, and products_retrieved is always 0. Upstream usage.total_tokens is still debited from limits.tokens when that limit is tracked (typically a few tokens), unless BYOK is active (see below).

BYOK — If the site has a merchant key stored via POST /byok, that key is used instead of the shared AskAgento LLM credentials. Token preflight and limits.tokens debit are skipped while BYOK is active (usage.billed_tokens is 0).

Token preflight (429 when limits.tokens is present and <= 0) applies when BYOK is not active.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> can be the public key or the secret key; use the public key in browser code and AI agent configs.

No request body. Response includes CORS headers (Access-Control-Allow-Origin, Access-Control-Allow-Headers including X-Askagento-Site-Id, X-Askagento-Api-Key, Content-Type) so browsers may POST /chatbot.

Precomputed cross-sell recommendations for the registered catalogue (stored in object storage). Built during installation from install-time catalogue similarity indexes (no LLM).

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Precomputed upsell recommendations for the registered catalogue (stored in object storage). Built during installation from install-time catalogue similarity indexes (no LLM).

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Search endpoint for text, image and voice search.

Omit modality 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. Prefer setting modality explicitly for MCP contracts so the search mode is declared rather than inferred.

Voice search (modality: voice): send a short spoken query as audio_base64 — a WAV file, 16-bit PCM, mono, 8–48 kHz (16 kHz recommended), at most 15 seconds — and optionally language (e.g. en-US, de_DE, fr; default en-US). The speech is converted to text and searched like a typed query; the response echoes it as transcript.

Each successful text, image or hybrid search debits one from limits.searches when that limit is tracked. A voice search debits 100 (speech-to-text is metered per second of audio), including when no speech is recognized. Monthly searches are spent first, then add-on pack searches. When fewer than 100 remain, a voice search returns 429 before any audio is processed.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> can be the public key or the secret key; use the public key in browser code and AI agent configs.

No request body. Response includes CORS headers (Access-Control-Allow-Origin, Access-Control-Allow-Headers including X-Askagento-Site-Id, X-Askagento-Api-Key, Content-Type) so browsers may POST /search.

Product suggestions for a search box, meant to be called while a shopper types (debounced, from the 2nd character). Each typed word must match the start of a word in the product title, category, tag, attribute value or SKU; one typo is tolerated in words of 4 or more letters, and words no product contains (e.g. "need" in "i need watch") are left out. The shop's synonyms (POST /merchandising) widen the match. No AI is involved and suggestions are not counted against limits.searches; run POST /search for the full AI search (e.g. on Enter).

Besides products, the answer lists popular searches that continue the typed text and the shop's search redirect for it, if any (the redirect also matches a redirect phrase that starts with the typed text, from 3 characters). An empty q (the shopper focused the empty search box) answers with trending searches of the last 7 days and the shop's best sellers.

Suggestions come from the catalogue of the latest sync (POST /install or POST /update). Answers may be cached by the browser for 60 seconds. A 1-character query returns nothing.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> can be the public key or the secret key; use the public key in browser code.

No request body. Response includes CORS headers (Access-Control-Allow-Origin, Access-Control-Allow-Headers including X-Askagento-Site-Id, X-Askagento-Api-Key) so browsers may GET /suggest.

Auto Filter pipeline (no LLM). analyze lists attribute names found in the synced catalog; generate echoes the merchant-selected canonical_filters; upload stores the selection on the catalog snapshot. Accepts action or filter_action (analyze, generate, upload, export). Optional canonical_filters is an alias for canonical_attributes.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Loads the site's product JSON, then runs analyze (suggest canonical names), generate (LLM proposals stored on products and catalogue), upload (persist generated labels into the catalogue in object storage), or export (download-ready payload). Debiting token quota uses the same mechanism as chat/search.

Modes: attributes, categories, tags. Actions: analyze, generate, upload, export.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Store or clear a merchant-supplied OpenAI or OpenRouter API key on the install record.

When a BYOK key is stored, POST /chatbot uses that key for inference and does not debit limits.tokens (the merchant pays their provider directly). Clearing removes the key and restores the shared AskAgento LLM path with normal token metering.

Providers: openai, openrouter only (OpenAI-compatible chat completions).

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Returns the current plan slug and display label for the site. Every API capability is available on every plan; the plan sets catalogue capacity and included monthly usage only.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Retrieve installation metadata.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Install the plugin.

Local (test) shops. A shop our servers cannot reach (localhost, .local, .test and similar names, private IP addresses, or a name that does not resolve publicly) installs in local mode, for testing:

• at most 100 products (403, local_too_many_products otherwise);
• each product's main image is sent inline as image_base64 (JPEG, PNG, WebP or GIF, at most 512 KB decoded; the plugin sends about 300 px JPEGs), because the service cannot download images from the shop. Without any readable image the install is rejected with 422 (no_product_images);
• variation images are not indexed;
• the catalogue is never re-indexed automatically: POST /update keeps the stored product data current, but changes reach search only after a reinstall.

Whether a shop is local is decided by the service from domain. Inline images from a shop that turns out to be reachable are ignored and its images are downloaded as usual.

Check that a shop can be reached from our servers before sending its catalogue to POST /install.

Installation reads product pages and images directly from the shop, so a shop that is local, resolves to a private address, or refuses image requests cannot be installed. Calling this first turns that into an immediate, explainable answer instead of a failure part-way through installation.

Send the shop domain and the URL of one product image. The check is a name check, a DNS lookup, and a single image fetch, so it returns in about a second.

verdict is one of:

• pass — proceed with POST /install.
• blocked — the install cannot succeed as configured; reason says why.
• inconclusive — the shop could not be judged (timeout, rate limit). Offer a retry rather than treating it as a failure.

A blocked verdict is a normal, successful response: the check ran and the answer is no. Only malformed requests return 4xx.

Treat unknown codes by their verdict — codes may be added.

No API key: this runs before POST /install issues one.

What shoppers asked for and did not find, over the last days full UTC days (at most 30; today is not included).

• searches — AI text searches whose best product match was too weak (or that found nothing), grouped by identical wording, most frequent first.
• chat_topics — chatbot questions grouped into topics such as "Ring sizing". unmatched counts the questions for which no matching product was found. chat_topics_source is ai when topics were grouped by the AI model, exact when only identical questions could be grouped, none without chat questions.

Only queries and topics asked at least twice are listed (up to 50 each). Email addresses, URLs and long numbers (phone or order numbers) are removed from the text before it is stored. Figures are rebuilt once a day shortly after midnight UTC.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Sent from the storefront once when a shopper session starts and once more when that session first uses AskAgento (search, chatbot or an AI recommendation), with ai: true. Each session_id is counted once; a session becomes AI-engaged at most once. These counts are the denominators of the conversion rates in GET /attribution/summary. session_id is a random identifier; it carries no personal data.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> may be the public key or the secret key.

Called from the shop's server when an order is paid, and again if it is later refunded or cancelled. A paid order is counted once per order_id (repeat reports return result: duplicate). A refunded or cancelled report takes a previously counted order back out of the day it was paid (result: reversed), or does nothing (result: not_found). Include attribution only when the shopper reached the order through AskAgento. Send no customer personal data.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Revenue influenced by AskAgento for the last days days (UTC, today included), read from daily figures kept up to date as orders and sessions are reported. An order is AskAgento-assisted when the shopper clicked a product in AI search, the chatbot or an AI recommendation within the shop's attribution window before checking out.

• ai_aov / site_aov — average order value of assisted orders vs. all orders.
• ai_conversion_rate — assisted orders per AI-engaged session.
• baseline_conversion_rate — other orders per session without AI engagement.
• roi_multiple — assisted revenue divided by plan.period_cost; null on the free plan or when the plan is billed in a different currency than the orders.

plan is what the site pays for AskAgento, read from its Stripe subscription (price, interval and active coupons, cached up to an hour) and spread over the window as period_cost. It is null when the cost cannot be determined.

Ratios are null when their denominator is zero. Refunded and cancelled orders are removed from the day they were paid.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Stores the shop's merchandising: search rules that pin, boost or bury products, whether out-of-stock products go last, and ranking weights that blend shop data into the search ranking. Each call replaces the stored settings. They are applied to /search, /chatbot, /mcp and the AskAgento app for ChatGPT.

Out-of-stock status and the ranking signals (sales, average rating, on sale, newness) come from the catalogue the shop last synced.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Uninstall the plugin and remove all indexed data for the site.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Push the shop's current product catalogue for an installed site (scheduled or manual sync). Stores product JSON in object storage and updates the install record's product-data hash.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.

Returns the current plan, remaining per-site limits (tokens, searches), the tier-level maximums, and the catalogue product count against the number of products the plan indexes. Every API capability is available on every plan; a plan sets only catalogue capacity and included monthly usage. When the catalogue is larger than the plan indexes (over_product_limit: true), catalogue-backed endpoints return 403 with code: product_limit_exceeded until the catalogue is covered by a larger plan or reduced in size.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers. <api_key> must be the secret key; the public key is rejected with 401.