Askagento API

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

AI Chatbot

POST

https://api.askagento.com/v1

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

AI Chatbot › Request Body

ChatbotRequest

action

string · enum

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

Enum values:

chat

health

Default: chat

ChatMessage[] · maxItems: 24

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 · max: 4096

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

Default: 1024

AI Chatbot › Responses

Chat reply with usage and limit information

ChatbotResponse

site_id

string · required

action

string · enum · required

Enum values:

chat

health

latency_ms

integer · required

Round-trip latency to the chat provider in milliseconds

object · required

reply

string · required

Text reply from the model

products_retrieved

integer · required

Number of catalogue products injected as context for action=chat; always 0 for health

limits_tokens_remaining

integer | null

Remaining token quota for the site after this call; null if no quota is set

POST/chatbot

curl https://api.askagento.com/v1/chatbot \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Askagento-Site-Id: <api-key>' \
  --header 'X-Askagento-Api-Key: <api-key>' \
  --data '{
  "action": "chat",
  "messages": [
    {
      "role": "system",
      "content": "content"
    }
  ],
  "max_completion_tokens": 1024
}'

Example Request Body

{
  "action": "chat",
  "messages": [
    {
      "role": "system",
      "content": "content"
    }
  ],
  "max_completion_tokens": 1024
}

json

Example Responses

{
  "site_id": "site_id",
  "action": "chat",
  "latency_ms": 0,
  "usage": {
    "total_tokens": 0
  },
  "reply": "reply",
  "products_retrieved": 0,
  "limits_tokens_remaining": 0
}

json

application/json

CORS for AI Chatbot

OPTIONS

https://api.askagento.com/v1

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

CORS for AI Chatbot › Responses

200

Empty JSON body

Auto Filter

POST

https://api.askagento.com/v1

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

Auto Filter › Request Body

FilterRequest

action

string · enum

Enum values:

analyze

generate

upload

export

filter_action

string · enum

Alias for action; supply either action or filter_action.

Enum values:

analyze

generate

upload

export

canonical_filters

string[]

Alias for canonical_attributes when generating attribute filters.

Auto Filter › Responses

Filter action result (analyze / generate / upload / export).

Shape depends on `mode` and `action`. `generated_preview`, `uploaded_products` (upload), `filename` (export), and informational `message`.

LabelFilterJsonResponse

site_id

string

mode

string

action

string

CORS for Auto Filter

OPTIONS

https://api.askagento.com/v1

/filter

CORS for Auto Filter › Responses

200

Empty JSON body

Installation status

GET

https://api.askagento.com/v1

/install

Install metadata only.

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

Installation status › Responses

Install status response

InstallStatusResponse

site_id

string

installed_at

string | null · date-time

status_message

string

status

string

Install plugin

POST

https://api.askagento.com/v1

/install

Install the plugin.

Install plugin › Request Body

InstallRequest

domain

string · required

Product[] · required

system

string · enum · required

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

Enum values:

woocommerce

knowledge_base

plugin_version

string

woocommerce_version

string

total_products

integer

shop_ip

string

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

Install plugin › Responses

Installation accepted for async processing

InstallAcceptedResponse

status

string · required

site_id

string · required

New site identifier; store with api_key for subsequent calls.

api_key

string · required

Install-time secret; required on all routes except POST /install (new installs) and OPTIONS preflights.

message

string · required

POST/install

curl https://api.askagento.com/v1/install \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "domain": "domain",
  "plugin_version": "plugin_version",
  "woocommerce_version": "woocommerce_version",
  "products": [
    {
      "id": 0,
      "title": "title",
      "name": "name",
      "description": "description",
      "short_description": "short_description",
      "sku": "sku",
      "price": "price",
      "regular_price": "regular_price",
      "sale_price": "sale_price",
      "price_html": "price_html",
      "stock_quantity": 0,
      "status": "status",
      "featured": true,
      "on_sale": true,
      "permalink": "https://www.example.com/path/to/resource",
      "image_url": "https://www.example.com/path/to/resource",
      "categories": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "tags": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "attributes": [
        {}
      ],
      "variations": [
        {}
      ],
      "date_created": "2024-08-25T15:00:00Z",
      "date_modified": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "total_products": 0,
  "shop_ip": "shop_ip",
  "system": "woocommerce"
}'

Example Request Body

{
  "domain": "domain",
  "plugin_version": "plugin_version",
  "woocommerce_version": "woocommerce_version",
  "products": [
    {
      "id": 0,
      "title": "title",
      "name": "name",
      "description": "description",
      "short_description": "short_description",
      "sku": "sku",
      "price": "price",
      "regular_price": "regular_price",
      "sale_price": "sale_price",
      "price_html": "price_html",
      "stock_quantity": 0,
      "status": "status",
      "featured": true,
      "on_sale": true,
      "permalink": "https://www.example.com/path/to/resource",
      "image_url": "https://www.example.com/path/to/resource",
      "categories": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "tags": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "attributes": [
        {}
      ],
      "variations": [
        {}
      ],
      "date_created": "2024-08-25T15:00:00Z",
      "date_modified": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "total_products": 0,
  "shop_ip": "shop_ip",
  "system": "woocommerce"
}

json

Example Responses

{
  "status": "accepted",
  "site_id": "site_id",
  "api_key": "api_key",
  "message": "message"
}

json

application/json

Auto Label

POST

https://api.askagento.com/v1

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

Auto Label › Request Body

LabelRequest

mode

string · enum · required

Enum values:

attributes

Auto Label › Responses

Success shape varies by mode and action (counts, previews, keys, catalogue upload status).

Shape depends on `mode` and `action`. `generated_preview`, `uploaded_products` (upload), `filename` (export), and informational `message`.

LabelFilterJsonResponse

site_id

string

mode

string

action

string

CORS for Auto Label

OPTIONS

https://api.askagento.com/v1

/label

CORS for Auto Label › Responses

200

Empty JSON body

AI Agents

POST

https://api.askagento.com/v1

/mcp

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.

AI Agents › Request Body

McpRequest

jsonrpc

string · enum · required

Enum values:

2.0

method

string · required

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

Request id (omit for notifications)

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

AI Agents › Responses

JSON-RPC 2.0 response (result or error)

McpResponse

jsonrpc

string · enum

Enum values:

2.0

object | null

error

object | null

CORS for AI Agents

OPTIONS

https://api.askagento.com/v1

/mcp

CORS for AI Agents › Responses

200

Empty JSON body

Current billing plan

GET

https://api.askagento.com/v1

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

Current billing plan › Responses

Plan response

PlanResponse

site_id

string

plan

string | null

Plan slug (e.g. starter, growth); null if no plan is set

plan_label

string | null

Human-readable plan label

trial

boolean

True while the site is on the install-time free trial of its plan

trial_ends_at

string | null

ISO-8601 UTC timestamp when the trial ends; null when not on a trial.

GET

https://api.askagento.com/v1

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

Recommendations JSON from object storage

RecommendationsPayload

site_id

string

generated_at

string

ISO 8601 timestamp (UTC) with Z suffix

object

Map of source product id to cross-sell targets (similarity-ranked)

object

Map of source product id (string) to ranked neighbor list

GET

https://api.askagento.com/v1

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

Recommendations JSON from object storage

RecommendationsPayload

site_id

string

generated_at

string

ISO 8601 timestamp (UTC) with Z suffix

object

Map of source product id to cross-sell targets (similarity-ranked)

object

Map of source product id (string) to ranked neighbor list

AI Search

POST

https://api.askagento.com/v1

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

AI Search › Request Body

SearchRequest

query

string

Text query (alias q)

q

string

Alias for query

image_base64

string

Base64 image; data URLs are accepted

modality

string · enum

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.

Enum values:

text

image

both

limit

integer · min: 1 · max: 50

Default: 12

AI Search › Responses

Ranked product hits

SearchResponse

site_id

string · required

modality

string · enum · required

Enum values:

text

image

both

SearchHit[] · required

query

string

Echoed text query when modality is text or both

CORS for AI Search

OPTIONS

https://api.askagento.com/v1

/search

CORS for AI Search › Responses

200

Empty JSON body

Update product data

POST

https://api.askagento.com/v1

/update

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.

Update product data › Request Body

UpdateRequest

Product[] · required

system

string · enum · required

Enum values:

woocommerce

domain

string

plugin_version

string

woocommerce_version

string

total_products

integer

Update product data › Responses

Product data accepted

UpdateResponse

status

string · required

site_id

string · required

synced_products

integer · required

update_needed

boolean · required

True when the catalogue hash changed on this sync (re-embed required). Unchanged-hash syncs do not clear a previously true flag.

message

string · required

POST/update

curl https://api.askagento.com/v1/update \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Askagento-Site-Id: <api-key>' \
  --header 'X-Askagento-Api-Key: <api-key>' \
  --data '{
  "domain": "domain",
  "plugin_version": "plugin_version",
  "woocommerce_version": "woocommerce_version",
  "products": [
    {
      "id": 0,
      "title": "title",
      "name": "name",
      "description": "description",
      "short_description": "short_description",
      "sku": "sku",
      "price": "price",
      "regular_price": "regular_price",
      "sale_price": "sale_price",
      "price_html": "price_html",
      "stock_quantity": 0,
      "status": "status",
      "featured": true,
      "on_sale": true,
      "permalink": "https://www.example.com/path/to/resource",
      "image_url": "https://www.example.com/path/to/resource",
      "categories": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "tags": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "attributes": [
        {}
      ],
      "variations": [
        {}
      ],
      "date_created": "2024-08-25T15:00:00Z",
      "date_modified": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "total_products": 0,
  "system": "woocommerce"
}'

Example Request Body

{
  "domain": "domain",
  "plugin_version": "plugin_version",
  "woocommerce_version": "woocommerce_version",
  "products": [
    {
      "id": 0,
      "title": "title",
      "name": "name",
      "description": "description",
      "short_description": "short_description",
      "sku": "sku",
      "price": "price",
      "regular_price": "regular_price",
      "sale_price": "sale_price",
      "price_html": "price_html",
      "stock_quantity": 0,
      "status": "status",
      "featured": true,
      "on_sale": true,
      "permalink": "https://www.example.com/path/to/resource",
      "image_url": "https://www.example.com/path/to/resource",
      "categories": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "tags": [
        {
          "id": 0,
          "name": "name",
          "slug": "slug"
        }
      ],
      "attributes": [
        {}
      ],
      "variations": [
        {}
      ],
      "date_created": "2024-08-25T15:00:00Z",
      "date_modified": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "total_products": 0,
  "system": "woocommerce"
}

json

Example Responses

{
  "status": "ok",
  "site_id": "site_id",
  "synced_products": 0,
  "update_needed": true,
  "message": "message"
}

json

application/json

Uninstall plugin

POST

https://api.askagento.com/v1

/uninstall

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.

Uninstall plugin › Request Body

UninstallRequest

system

string · enum · required

Enum values:

woocommerce

knowledge_base

domain

string

plugin_version

string

woocommerce_version

string

Uninstall plugin › Responses

Uninstall completed

StatusOkResponse

status

string

Usage limits

GET

https://api.askagento.com/v1

/usage

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.

Usage limits › Responses

Usage response

UsageResponse

site_id

string

plan

string | null

Plan slug; null if no plan is set

plan_label

string | null

trial

boolean

True while the site is on the install-time free trial of its plan

trial_ends_at

string | null

ISO-8601 UTC timestamp when the trial ends; null when not on a trial.

UsageLimits

Current remaining limits for this site; null if no limits are tracked

UsageLimits

Tier-level maximums for the current plan; null if no plan is set. Includes a products field (the plan's product cap) in addition to tokens/searches.

product_count

integer | null

Number of products in the shop's catalogue; null if not yet recorded

max_products

integer | null

Maximum products allowed on the current plan; null if no plan is set

over_product_limit

boolean

True when the catalogue exceeds the plan's product cap. While true, AI features are blocked until the merchant upgrades or reduces the catalogue.

Askagento API

AI Chatbot

AI Chatbot › Request Body

AI Chatbot › Responses

CORS for AI Chatbot

CORS for AI Chatbot › Responses

Auto Filter

Auto Filter › Request Body

Auto Filter › Responses

CORS for Auto Filter

CORS for Auto Filter › Responses

Installation status

Installation status › Responses

Install plugin

Install plugin › Request Body

Install plugin › Responses

Auto Label

Auto Label › Request Body

Auto Label › Responses

CORS for Auto Label

CORS for Auto Label › Responses

AI Agents

AI Agents › Request Body

AI Agents › Responses

CORS for AI Agents

CORS for AI Agents › Responses

Current billing plan

Current billing plan › Responses

AI Recommend (cross-sell)

AI Recommend (cross-sell) › Responses

AI Recommend (upsell)

AI Recommend (upsell) › Responses

AI Search

AI Search › Request Body

AI Search › Responses

CORS for AI Search

CORS for AI Search › Responses

Update product data

Update product data › Request Body

Update product data › Responses

Uninstall plugin

Uninstall plugin › Request Body

Uninstall plugin › Responses

Usage limits

Usage limits › Responses