Welcome to AskAgento API

Askagento HTTP API

Authentication:

• X-Askagento-Site-Id: <site_id>
• X-Askagento-Api-Key: <api_key>

Every request except POST /install, POST /install/verify and OPTIONS preflights requires authentication.

<api_key> is one of the two keys POST /install returns:

• the secret key (response field api_key). Keep it on your server and never put it in a web page or browser code. It works on every authenticated route.
• the public key (response field public_key, starts with pk_). It is safe to embed in storefront pages and to give to AI agents, and it works only on POST /chatbot, GET /suggest, POST /search, POST /mcp and POST /sessions/report. Every other route rejects it with 401.

Routes:

• GET /attribution/summary — revenue attributed to AskAgento: totals, AOV, conversion rates and daily figures.
• POST /byok — store or clear a merchant-supplied LLM key (BYOK) for chatbot inference.
• OPTIONS /chatbot — CORS preflight; no API key.
• POST /chatbot — AI Chatbot. Chatbot with retrieved product context (LLM; response includes products_retrieved). Accepts the public key.
• OPTIONS /filter — CORS preflight; no API key.
• POST /filter — Auto Filter. Attributes filters with mode=attributes.
• POST /install — accept installation (async); no API key; response includes new site_id, secret api_key and public_key.
• GET /install — install status.
• OPTIONS /install/verify — CORS preflight; no API key.
• POST /install/verify — check that the shop is publicly reachable before installing; no API key.
• OPTIONS /label — CORS preflight; no API key.
• POST /label — Auto Label. Analyze / generate / upload / export auto-labels for attributes, categories, or tags.
• OPTIONS /mcp — CORS preflight; no API key.
• POST /mcp — AI Agents MCP. Accepts the public key. JSON-RPC 2.0 MCP endpoint; tools: 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.
• POST /orders/report — report a paid, refunded or cancelled order, with its AskAgento attribution.
• GET /plan — current subscription plan.
• GET /recommend/cross-sell — AI Recommend cross-sell bundle.
• GET /recommend/upsell — AI Recommend upsell bundle.
• OPTIONS /search — CORS preflight; no API key.
• POST /search — AI Text, Image or Voice Search. Semantic text/image search; voice (spoken query, converted to text) uses 100 searches per request. Accepts the public key.
• OPTIONS /sessions/report — CORS preflight; no API key.
• POST /sessions/report — count a storefront session for conversion-rate reporting. Accepts the public key.
• OPTIONS /suggest — CORS preflight; no API key.
• GET /suggest — Autocomplete. Product suggestions (title, link, image, price) for what a shopper is typing; title matching without AI, not counted as a search. Accepts the public key.
• POST /update — push current catalogue product data for an installed site.
• POST /uninstall — tear down remote data for the authenticated site.
• GET /usage — plan, remaining limits, tier maximums, and catalogue capacity.