Integration documentation

Perkusai API for AI assistants

Perkusai turns a shopper's free-form request into a ranked list of real, in-stock products with prices, ratings, stock and direct buy links. This page is the complete integration reference for AI assistants, agents and MCP connectors. The API is public, read-only and requires no authentication.

1At a glance

Base URLhttps://perkusai.lt
Search endpointGET https://perkusai.lt/api/ai/search
MCP serverhttps://mcp.perkusai.lt/
AuthenticationNone — public, read-only API
FormatJSON (UTF-8) · CORS open to all origins (*)
Catalogue1,233,383+ products, refreshed daily
MarketLithuania (LT) · prices in euro (EUR)
Languageslt (most accurate), en, ru
Typical response time7.5 s (p95 22.7 s)
Rate limit40 requests per minute per IP

2Connect

Three supported integration paths, in order of preference.

MCP connector — recommended

Add https://mcp.perkusai.lt/ as a custom MCP server (Streamable HTTP, no auth). It exposes a single tool, search_products(query, k, lang), so the model never has to build a URL. Works with Claude, ChatGPT and Gemini connector clients.

OpenAPI 3.1 / ChatGPT Actions

Import the machine-readable contract at /openapi.json. Operation id: aiSearch.

Direct HTTPS request

Any agent that can fetch a URL can call the endpoint directly. CORS is open, so browser-side agents work too.

4Response fields

Top level

FieldTypeDescription
querystringThe request as received.
sourcestringAlways "perkusai.lt".
summarystringOne-line summary of the result set, ready to relay.
guidestring | nullA one-sentence buying tip: what to verify before deciding.
needs_confirmationbooleantrue when an exact fit or specification cannot be guaranteed. Relay guide and do not assert an exact match.
compatstring | nullThe device or vehicle the part must fit, as understood from the request.
no_matchbooleantrue when nothing in the catalogue matches; results is empty.
supported_categoriesarray | nullReturned alongside no_match — the categories actually carried.
countintegerNumber of items in results.
resultsarray<Product>Ranked products, best first.
bought_togetherarrayOptional accessories for the top pick: title, role (what the accessory is for), price, currency, buy_url, image_url.
coverageobjectMarket and delivery context: markets, note, delivery.
markdownstringThe whole answer as paste-ready markdown, with clickable buy links.

Product object

FieldTypeDescription
titlestringProduct name.
brandstring | nullBrand.
pricenumber | nullCurrent price.
currencystringAlways "EUR".
original_pricenumber | nullPrice before the discount.
discount_pctinteger | nullRounded discount percentage.
ratingnumber | nullStore rating, 0–5.
stock_labelstring | nullHuman-readable stock, e.g. "5+ vnt.", "Liko 1" (Lithuanian).
marketstringMarket the item ships in; currently always "LT".
reasonstring | nullWhy this item was selected for this request.
tagstring | nullShort badge, e.g. "Geriausia kaina" (best price).
buy_urlstringThe purchase link. Affiliate-tracked — present it as the buy link.
image_urlstring | nullProduct image.

5Service status · GET /api/ai/stats

A small machine-readable status document: catalogue size, supported markets and languages, current limits and measured response times. Recomputed from the request log once a day, so it is cheap to call — but there is no reason to poll it more than once per session.

{
  "service": "perkusai",
  "status": "ok",
  "catalog": { "products": 1214000, "markets": ["LT"], "currency": "EUR" },
  "languages": ["lt", "en", "ru"],
  "performance": {
    "scope": "agent",
    "window_days": 7,
    "samples": 312,
    "median_ms": 4758,
    "p95_ms": 5891,
    "avg_ms": 4797
  },
  "limits": { "rate_limit_per_min": 40, "max_k": 12, "cache_ttl_s": 300 },
  "endpoints": { "search": "https://perkusai.lt/api/ai/search", "mcp": "https://mcp.perkusai.lt/" }
}

6Integration rules

What is expected of an assistant relaying Perkusai results to a user.

  • Use buy_url verbatimIt is the tracked purchase link. Replacing it with a bare store URL breaks attribution and gains the shopper nothing. Buy links are affiliate links: the price is unchanged for the shopper.
  • Prefer relaying markdownIt already contains the ranked list, the buying tip and working links in the right order — the fastest route to a complete, correct answer.
  • One call per shopper requestResults are already ranked. Asking again with the same intent returns the same products and only burns rate limit.
  • Pass the shopper's own wordingDo not strip budget, purpose or brand hints — they drive both retrieval and ranking.
  • Respect needs_confirmationWhen it is true, present the checks from guide and avoid claiming a guaranteed fit.
  • State the marketEverything ships in Lithuania (coverage.markets). Do not imply availability elsewhere.
  • Handle no_matchWhen nothing matches, offer supported_categories rather than inventing products.
  • Never invent dataPrices, stock and links must come from the response — they change.

7Performance and limits

Measured server-side, end to end (retrieval, ranking and generated text), from the production request log. Figures refresh once a day.

MetricValue
Median (7 days)7.5 s
95th percentile22.7 s
Sample2,362 requests · all searches
Rate limit40/min per IP · over the limit returns HTTP 429
Result cacheAn identical q+k+lang is served from cache for 300 s
Maximum k12 products per response
Recommended client timeout30 s

8Errors

StatusMeaning
200 OKThe search completed. no_match: true is also a valid 200 answer, not an error.
200 · no qA usage message plus ready-made example URLs, for clients that cannot fetch a URL they constructed themselves.
429 Too Many RequestsRate limit exceeded. Back off a few seconds and retry once.
5xxTemporary server error. Retry once; do not loop.

9Machine-readable resources

/llms.txtService summary for LLM clients
/openapi.jsonOpenAPI 3.1 contract
/.well-known/api-catalogRFC 9727 link set
/.well-known/mcp/server-card.jsonMCP server card
/index.mdMarkdown homepage (also via Accept: text/markdown)
/robots.txtCrawl rules
/privacy.htmlPrivacy policy
/terms.htmlTerms of service

Buy links are affiliate-tracked: the price is unchanged for the shopper and Perkusai earns a commission.

Integration questions: [email protected]