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, POST /search and POST /mcp. Every other route rejects it with 401.

Routes:

• 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.
• 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 Image or Text Search. Semantic text/image 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.