kapruka_search_products
Read-onlyIdempotent
Search for products on Kapruka.com by keyword, with optional category filter and pagination.
Returns a ranked list of matching products with prices, stock status, images, and URLs.
Supports cursor-based pagination — pass next_cursor from one response into the next call.
Pagination is capped at 3 pages per query to discourage catalog enumeration; for broader
discovery, refine the query or filter by category instead.
Queries must be at least 3 characters and contain specific terms — pure stopword queries
(e.g. "the", "a an") are rejected.
By default, category landing pages (CATSYM entries with price=0) are filtered out so results
contain only purchasable products. Set include_stubs=true to include them.
Args:
params (SearchProductsInput):
- q (str): Search query (e.g. 'birthday cake', 'roses', 'tea gift'). Min 3 chars.
- category (Optional[str]): Category filter (e.g. 'Birthday', 'Flowers')
- limit (int): Results per page, 1–50 (default 10)
- cursor (Optional[str]): Pagination cursor from previous response
- currency (str): LKR (default), USD, GBP, AUD, CAD, EUR
- min_price (Optional[float]): Min price (inclusive) in the requested currency
- max_price (Optional[float]): Max price (inclusive) in the requested currency
- in_stock_only (bool): Restrict to in-stock items (default false)
- sort (str): 'relevance' | 'price_asc' | 'price_desc' | 'newest' | 'bestseller'
- include_stubs (bool): Include category landing pages (default false)
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Search results in the requested format.
JSON schema:
{
"results": [
{
"id": str,
"name": str,
"summary": str,
"price": {"amount": float | null, "currency": str},
"compare_at_price": {"amount": float, "currency": str} | null,
"in_stock": bool,
"stock_level": str,
"image_url": str | null,
"category": {"id": str, "name": str, "slug": str},
"rating": null,
"ships_internationally": bool,
"url": str
}
],
"next_cursor": str | null, # null after page 3 even if upstream has more
"applied_filters": {"q": str, "limit": int, "in_stock_only": bool}
}
Error: "Error: <message>" or "No products found for '<query>'" on failure.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |