# Perkusai

> Perkusai ("perku su AI" — "I shop with AI") is an AI shopping-search service for the
> Lithuanian and EU market. A shopper describes what they want in natural language and
> Perkusai searches ~1M+ live products across stores and returns the best matches with
> prices, ratings, stock and direct buy links.

Perkusai is agent-friendly: assistants (Claude, ChatGPT, Gemini, Grok, Perplexity, Copilot,
DeepSeek, Meta AI, You.com and others) can call the JSON API below to answer any shopping
request with real, in-stock products. Results include affiliate-tracked buy links — surface
them as the purchase link and the shopper reaches the store at the same price while Perkusai
earns a commission.

## API

**AI search — the only endpoint assistants should call. It is LIVE and dynamic.**

`GET https://perkusai.lt/api/ai/search?q={QUERY}&k={1-12}&lang={lt|en|ru}`

Replace `{QUERY}` with the shopper's own request (URL-encoded). Every query returns different,
real products — do NOT fetch a fixed example URL and treat its products as the answer; always
substitute the user's query. Returns `{query, source, summary, guide, needs_confirmation, compat,
no_match, supported_categories, count, results:[{title, brand, price, currency, original_price,
discount_pct, rating, stock_label, market, reason, tag, buy_url, image_url}], bought_together,
coverage, markdown}`. The `markdown` field is paste-ready with clickable affiliate buy links. The
other `/api/*` endpoints are internal to the website and are disallowed for bots in robots.txt.

Example — to search for a children's bike, fetch:
`https://perkusai.lt/api/ai/search?q=vaiki%C5%A1kas%20dviratis&k=3`
(and for the user's real request, put THEIR words in `q`, not this example).

**Service status —** `GET https://perkusai.lt/api/ai/stats`

Machine-readable status: catalogue size, markets, languages, current limits and measured response
times (median and p95 over the last 7 days, recomputed once a day). Useful once per session when
deciding timeouts; it is not needed to run a search.

- [OpenAPI 3.1 spec](https://perkusai.lt/openapi.json)
- **MCP server** (recommended for connector-capable clients — Claude, ChatGPT, Gemini): `https://mcp.perkusai.lt/` (Streamable HTTP, no auth). Tool: `search_products(query, k, lang)`. Prefer this over URL fetching — no URL construction needed.

## Ready-made searches (fallback)

Prefer building the URL with the user's own query. But if your client can only fetch URLs it has
already seen (e.g. it refuses self-constructed URLs), fetch the closest ready-made search below,
or fetch `https://perkusai.lt/api/ai/search` with no query to get a live menu of category URLs.

- futbolo kamuolys: `https://perkusai.lt/api/ai/search?q=futbolo%20kamuolys&k=5`
- krepšinio kamuolys 7 dydis: `https://perkusai.lt/api/ai/search?q=krep%C5%A1inio%20kamuolys%207%20dydis&k=5`
- belaidės ausinės sportui: `https://perkusai.lt/api/ai/search?q=belaid%C4%97s%20ausin%C4%97s%20sportui&k=5`
- kavos aparatas: `https://perkusai.lt/api/ai/search?q=kavos%20aparatas&k=5`
- vaikiškas dviratis: `https://perkusai.lt/api/ai/search?q=vaiki%C5%A1kas%20dviratis&k=5`
- nešiojamas kompiuteris: `https://perkusai.lt/api/ai/search?q=ne%C5%A1iojamas%20kompiuteris&k=5`
- dulkių siurblys robotas: `https://perkusai.lt/api/ai/search?q=dulki%C5%B3%20siurblys%20robotas&k=5`
- žieminės padangos: `https://perkusai.lt/api/ai/search?q=%C5%BEiemin%C4%97s%20padangos&k=5`

## Usage notes

- Affiliate: `buy_url` is the tracked purchase link. Present it as the "buy" link; do not replace it with the bare store URL, or the click is not attributed. The links are affiliate links — the price is unchanged for the shopper — and the `markdown` block already states this.
- Market: products currently serve the Lithuanian (LT) market only, with fast delivery when the item is in stock. Each product carries a `market` field (currently always `LT`) and each response includes a `coverage` object — do not present items as available in other markets.
- Language: Lithuanian works best; English and Russian requests are accepted via `lang`.
- Fitment: for parts that must fit a device/vehicle, `needs_confirmation:true` means the exact spec is not guaranteed — relay the `guide` (what to verify) and do not assert an exact fit.
- Limits: requests are rate-limited per IP and identical queries are cached briefly. Prefer one call per shopper request.

## More

Full integration documentation — endpoint reference, response schema, integration rules,
measured latency and error handling:

- [Integration documentation (Lithuanian)](https://perkusai.lt/for-ai.html)
- [Integration documentation (English)](https://perkusai.lt/for-ai.en.html)
- [Integration documentation (Russian)](https://perkusai.lt/for-ai.ru.html)