API docs by Redocly

Askagento Plugin API (1.8.1)

Download OpenAPI specification:

Askagento HTTP API

POST /install (new installs) and all OPTIONS preflights require no headers; POST /install returns the new site_id and api_key.

Authentication Every request except POST /install and OPTIONS preflights is authenticated with two headers:

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

Routes:

  • OPTIONS /chatbot — CORS preflight; no API key.
  • POST /chatbot — AI Chatbot. Chatbot with retrieved product context (LLM; response includes products_retrieved).
  • 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 and api_key.
  • GET /install — install status.
  • 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. 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 billing 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.
  • 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, and tier maximums.

Askagento API

Install, uninstall, status, recommendations, search, chatbot, label, filter, MCP, plan, usage.

CORS for AI Chatbot

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.

Responses

Response samples

Content type
application/json
{ }

AI Chatbot

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

Token preflight (429 when limits.tokens is present and <= 0) applies to both actions.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
action
string
Default: "chat"
Enum: "chat" "health"

chat — full conversation; last user turn drives product retrieval (see POST /chatbot). health — connectivity probe; messages optional and ignored; max_completion_tokens ignored.

Array of objects (ChatMessage) <= 24 items

Required when action=chat (non-empty after normalization); omitted or ignored for health. Up to 24 turns; each content truncated to 12 000 chars.

max_completion_tokens
integer <= 4096
Default: 1024

Alias max_tokens also accepted; capped at 4096. Ignored when action=health (server uses 3).

Responses

Request samples

Content type
application/json
{
  • "action": "chat",
  • "messages": [
    ],
  • "max_completion_tokens": 1024
}

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "action": "chat",
  • "latency_ms": 0,
  • "usage": {
    },
  • "reply": "string",
  • "products_retrieved": 0,
  • "limits_tokens_remaining": 0
}

CORS for Auto Filter

Responses

Response samples

Content type
application/json
{ }

Auto Filter

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

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.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
action
string
Enum: "analyze" "generate" "upload" "export"
filter_action
string
Enum: "analyze" "generate" "upload" "export"

Alias for action; supply either action or filter_action.

canonical_filters
Array of strings

Alias for canonical_attributes when generating attribute filters.

Responses

Request samples

Content type
application/json
{
  • "action": "analyze",
  • "filter_action": "analyze",
  • "canonical_filters": [
    ]
}

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "mode": "string",
  • "action": "string"
}

Install plugin

Install the plugin.

Request Body schema: application/json
required
domain
required
string
plugin_version
string
woocommerce_version
string
required
Array of objects (Product)
total_products
integer
shop_ip
string

Optional IPv4 string for the shop host (plugin may send DNS resolution result).

system
required
string
Enum: "woocommerce" "knowledge_base"

woocommerce — full catalogue with image + text data. knowledge_base — text-only Confluence/article chunks for askagento.com chat.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "plugin_version": "string",
  • "woocommerce_version": "string",
  • "products": [
    ],
  • "total_products": 0,
  • "shop_ip": "string",
  • "system": "woocommerce"
}

Response samples

Content type
application/json
{
  • "status": "accepted",
  • "site_id": "string",
  • "api_key": "string",
  • "message": "string"
}

Installation status

Install metadata only. Does not return recommendation data — use GET /recommend/upsell for the stored upsell bundle.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

Authorizations:
(InstallSiteIDInstallApiKey)

Responses

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "installed_at": "2019-08-24T14:15:22Z",
  • "status_message": "string",
  • "status": "ok"
}

CORS for Auto Label

Responses

Response samples

Content type
application/json
{ }

Auto Label

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

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.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
mode
required
string
Enum: "attributes" "categories" "tags"
action
required
string
Enum: "analyze" "generate" "upload" "export"
canonical_attributes
Array of strings
canonical_categories
Array of strings
canonical_tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "mode": "attributes",
  • "action": "analyze",
  • "canonical_attributes": [
    ],
  • "canonical_categories": [
    ],
  • "canonical_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "mode": "string",
  • "action": "string"
}

CORS for AI Agents

Responses

Response samples

Content type
application/json
{ }

AI Agents

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

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

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 (query 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.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
jsonrpc
required
string
Value: "2.0"
(string or null) or (integer or null)

Request id (omit for notifications)

method
required
string

One of: initialize, notifications/initialized, tools/call, tools/list

object

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": {...}}

Responses

Request samples

Content type
application/json
{
  • "jsonrpc": "2.0",
  • "id": "string",
  • "method": "string",
  • "params": { }
}

Response samples

Content type
application/json
{
  • "jsonrpc": "2.0",
  • "id": "string",
  • "result": { },
  • "error": {
    }
}

Current billing plan

Returns the current plan slug and display label for the site.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

Authorizations:
(InstallSiteIDInstallApiKey)

Responses

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "plan": "string",
  • "plan_label": "string",
  • "trial": true,
  • "trial_ends_at": "string"
}

AI Recommend (cross-sell)

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.

Authorizations:
(InstallSiteIDInstallApiKey)

Responses

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "generated_at": "string",
  • "cross_sells": {
    },
  • "recommendations": {
    }
}

AI Recommend (upsell)

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.

Authorizations:
(InstallSiteIDInstallApiKey)

Responses

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "generated_at": "string",
  • "cross_sells": {
    },
  • "recommendations": {
    }
}

CORS for AI Search

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.

Responses

Response samples

Content type
application/json
{ }

AI Search

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

Body: Omit modality to infer: query/q only → text, image_base64 only → image, both → hybrid (both). Set modality to text, image, or both explicitly. Hybrid fuses semantic text and image matches (same weights as upsell). Default limit 12 (1–50).

Each successful search debits one from limits.searches when that limit is tracked.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
query
string

Text query (alias q)

q
string

Alias for query

image_base64
string

Base64 image; data URLs are accepted

modality
string
Enum: "text" "image" "both"

Omit for automatic modality: text if only query/q, image if only image_base64, both if query and image are present. both requires query (≥2 chars) and image_base64.

limit
integer [ 1 .. 50 ]
Default: 12

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "q": "string",
  • "image_base64": "string",
  • "modality": "text",
  • "limit": 12
}

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "modality": "text",
  • "query": "string",
  • "results": [
    ]
}

Update product data

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.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
domain
string
plugin_version
string
woocommerce_version
string
required
Array of objects (Product)
total_products
integer
system
required
string
Value: "woocommerce"

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "plugin_version": "string",
  • "woocommerce_version": "string",
  • "products": [
    ],
  • "total_products": 0,
  • "system": "woocommerce"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "site_id": "string",
  • "synced_products": 0,
  • "update_needed": true,
  • "message": "string"
}

Uninstall plugin

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.

Authorizations:
(InstallSiteIDInstallApiKey)
Request Body schema: application/json
required
system
required
string
Enum: "woocommerce" "knowledge_base"
domain
string
plugin_version
string
woocommerce_version
string

Responses

Request samples

Content type
application/json
{
  • "system": "woocommerce",
  • "domain": "string",
  • "plugin_version": "string",
  • "woocommerce_version": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Usage limits

Returns the current plan, remaining per-site limits (tokens, searches), the tier-level maximums, and the catalogue product count against the plan's product cap. When the catalogue exceeds the cap (over_product_limit: true), AI features are blocked until the merchant upgrades or reduces the catalogue.

Authentication: Send X-Askagento-Site-Id: <site_id> and X-Askagento-Api-Key: <api_key> headers.

Authorizations:
(InstallSiteIDInstallApiKey)

Responses

Response samples

Content type
application/json
{
  • "site_id": "string",
  • "plan": "string",
  • "plan_label": "string",
  • "trial": true,
  • "trial_ends_at": "string",
  • "limits": {
    },
  • "plan_max_limits": {
    },
  • "product_count": 0,
  • "max_products": 0,
  • "over_product_limit": true
}