Fordeal.ai price comparison
Price comparison for Czechia and Slovakia: find where a product is cheapest today, with product price, shipping, total price, capture time and shop trust for every offer. Public remote MCP server (Streamable HTTP), no API key for public tools.
Hosted MCP Server
npx add-mcp 'https://fordeal.ai/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
First request
A request for the lowest price of one product, including shipping to the chosen country.
The samples contain a placeholder key. Once you create a key in step 1, yours is filled in. Without a key the request works too, at 10 requests per minute.
Command line: macOS, Linux, Windows 10 or later.
Copy
curl -s "https://fordeal.ai/api/v1/deals/best-price?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ" \
-H "Authorization: Bearer fd_live_YOUR_KEY" \
-H "Accept: application/json"
Below is one call and its shortened answer. headline is the sentence for a person, best.url leads to the shop through /go, and commission_disclosure must be shown to the buyer.
Example answer (illustrative numbers, not today's price)
{"verdict":"buy_now",
"headline":"Kupte teď v obchodě Datart za 25 990 Kč.",
"sort":"product",
"best":{"shop":{"name":"Datart","trust":"verified","rating":0.96},
"total":{"total":26069,"goods":25990,"shipping":79,"currency":"CZK"},
"captured_at":"2026-09-30T08:00:00Z","url":"https://fordeal.ai/go/2pwgnq5cwj/…"},
"alternatives":{"cheapest_cross_border":{"shop":{"name":"NAY","country":"SK"},"total":{"total":27806}}},
"offers":[…],"history":{"days":90,"lowest":25990,"points":[…]},
"commission_disclosure":"When you buy through a Fordeal link, …"}
Connect over MCP or REST
Streamable HTTP MCP endpoint; add it to Claude, ChatGPT, Cursor or any MCP client.
Addresses
- MCP endpoint https://fordeal.ai/mcp Copy
- REST API base URL https://fordeal.ai/api/v1 Copy
- OpenAPI 3.1 https://fordeal.ai/api/openapi.json Copy
- llms.txt https://fordeal.ai/llms.txt Copy
- MCP manifest https://fordeal.ai/.well-known/mcp.json Copy
REST request samples
The same tools over HTTP, documented in the OpenAPI file. Results are stored and shareable at /api/v1/deals/results/{slug}. Every offer also carries marketplace (platform, seller, ships-from country, price type; null for an ordinary shop) and total.shippingSource (offer, shop_rule or unknown: where the shipping cost comes from).
GET https://fordeal.ai/api/v1/deals/best-price?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ
GET https://fordeal.ai/api/v1/deals/best-price?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ&sort=total
GET https://fordeal.ai/api/v1/deals/history/apple-iphone-17-256-gb?days=365
GET https://fordeal.ai/api/v1/deals/daily?country=CZ&category=televize
GET https://fordeal.ai/api/v1/deals/search?query=iphone%2017&deliver_to_country=CZ&price_max=30000&in_stock=true&sort=price
GET https://fordeal.ai/api/v1/deals/abroad?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ
GET https://fordeal.ai/api/v1/deals/shops/compared?deliver_to_country=SK
GET https://fordeal.ai/api/v1/digital/compare?category=ai-chat&deliver_to_country=CZ
GET https://fordeal.ai/api/v1/digital/mobile?country=CZ&data_gb=10&minutes=300&no_commitment=true
GET https://fordeal.ai/api/v1/digital/energy?commodity=electricity&distributor=cez-distribuce&rate=D02d&mwh=2.5
In short
The web page, the REST API and the MCP server return the same data: what a person sees, an agent gets. find_best_price with a query and the buyer's country returns the whole card: verdict, main offer (`best`) with product price, shipping and capture time, alternatives and history. Every answer follows the same rules as the website and carries the commission disclosure, which must be shown to the buyer.
Tools
| search | Browse products by text, category or filters (price range, brand, in stock, on sale, sort): action search. Also trending, most_searched and rows. Every product comes with its lowest price. |
|---|---|
| product | One product's card: action find (text, model, EAN or URL plus country; sort=total counts shipping), get (by slug), variants, history (up to 365 days) and abroad. Send the buyer to best.url and say the product price, the shipping and when it was checked. |
| deals | action daily: the biggest price drops of the last 24 hours at rated shops, per country and category. action coupons: coupon codes and promotions valid today, with the tracked link. |
| digital | Digital services by price per month from official price lists: action compare (AI, streaming, music, VPN, cloud, office), api_costs (the cost of an AI API for a given usage) and history (recorded price changes). |
| telecom | In preparation, unverified: the answer carries status: in_preparation and verified: false; present the result as an estimate, never as a recommendation. Home internet (action internet) and mobile tariffs (action mobile) from official price lists. |
| energy | Household electricity and gas: action compare or from_bill (ranked by the yearly bill), unit_prices, history, suppliers, appliance (yearly cost of a fridge, washer or heating) and the fixation-end alert (watch, watch_status, watch_confirm, watch_cancel). |
| insurance | Insurance as a guide: what to compare for each kind and the insurers' official websites; no price, no ranking, no commission (Fordeal is not an insurance intermediary). |
| shops | action list: the shops compared for a country with rating and trust label. For a shop joining: check_feed, register, status, verify_domain, diagnostics; mine and statistics need the shop person's access token. |
| price_watch | A price watch alerts when a product's total reaches a target. Without an account: watch, status, manage (the token t of the e-mail link). With the person's access token: list, set, update, delete. |
| favorites | The person's saved products and digital plans: action list, add, remove. Needs the person's access token. |
| comparisons | The person's saved comparisons: action list, save, share (link) and delete. Needs the person's access token. |
| lists | The person's named lists: action list, create, update, delete, add and remove a product or digital plan. Needs the person's access token. |
| my_account | The person's account: action profile, update, sign_out and delete. Needs the person's access token. |
| contact | action message (a question, support, a personal-data request), cooperation (partners, media, creators), issue (a wrong price, variant, category or shop) and illegal (report illegal content). No account needed. |
| help | lovec.agents.tools.mcpHelp |
Actions that write
The tools above only read. The ones below write: contact (action issue) may be called by anyone, the account tools only with the signed-in person's access token (Authorization: Bearer, the token the website holds after the e-mail sign-in link). An agent's API key or no key opens no account, and every read and write applies only to the account of the token.
contact (issue) | Reports a wrong price, variant, category or shop of one offer. No account needed. |
|---|---|
energy (watch, watch_status, watch_confirm, watch_cancel) | Fixation-end watcher: the person's e-mail and end date; double opt-in (the person confirms by e-mail), one alert 45 days before the end, cancel link in every mail. |
price_watch (list, set, update, delete) | The person's price watches: list, create, change the target or pause, delete. |
favorites (list, add, remove) | The person's saved products and digital plans. |
comparisons (list, save, share, delete) | The person's saved comparisons, and a share link for one. |
Their REST routes: the same tools under /api/v1/me/… (account) and /api/v1/deals/issues.
POST /api/v1/digital/energy/watches energy watch
POST /api/v1/digital/energy/watches/confirm energy watch_confirm
POST /api/v1/digital/energy/watches/cancel energy watch_cancel
POST /api/v1/shops/register shops register
POST /api/v1/deals/shops/verify-ownership shops verify_domain
GET /api/v1/shops/mine shops mine
GET /api/v1/shops/{slug}/statistics shops statistics
POST /api/v1/price-watches/guest price_watch watch
POST /api/v1/price-watches/link price_watch manage
GET /api/v1/me/price-watches price_watch list
POST /api/v1/me/price-watches price_watch set
POST /api/v1/me/price-watches/{id} price_watch update
POST /api/v1/me/price-watches/{id}/delete price_watch delete
GET /api/v1/me/favorites favorites list
POST /api/v1/me/favorites favorites add
POST /api/v1/me/favorites/remove favorites remove
GET /api/v1/me/comparisons comparisons list
POST /api/v1/me/comparisons comparisons save
POST /api/v1/me/comparisons/{id}/share comparisons share
POST /api/v1/me/comparisons/{id}/delete comparisons delete
GET /api/v1/me/lists lists list
POST /api/v1/me/lists lists create
POST /api/v1/me/lists/{id} lists update
POST /api/v1/me/lists/{id}/delete lists delete
POST /api/v1/me/lists/{id}/items lists add
POST /api/v1/me/lists/{id}/items/remove lists remove
GET /api/v1/me/profile my_account profile
POST /api/v1/me/profile my_account update
POST /api/v1/me/logout my_account sign_out
POST /api/v1/me/account/delete my_account delete
POST /api/v1/contact/messages contact message
POST /api/v1/cooperation/inquiries contact cooperation
POST /api/v1/deals/issues contact issue
POST /api/v1/deals/content-notices contact illegal
Rules every answer follows
- Ranking is by product price (ČNB rate of the day) and shop trust only; the shipping to the country is on every offer separately and sort=total ranks by the sum. No paid placement.
- A shop on the ČOI or SOI risk list is never shown. An unrated shop is never
best. - A price older than 36 hours or an offer with unknown shipping is never
best; every offer carries captured_at and blockers. - Cross-border offers carry cross_border: EU warranty, returns, support languages.
- commission_disclosure is part of every answer and must be shown to the buyer.
Examples: requests and answers
Each call as curl (REST) and as an MCP JSON-RPC body, with the answer shortened (arrays show their first element). The test suite runs every one of them against the application, so the field names here are the real ones.
search_products · Search with paging: products matching a query, with total_matches and offset.
REST
curl -s "https://fordeal.ai/api/v1/deals/search?query=iphone+16+128&deliver_to_country=CZ&limit=2&offset=0"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_products",
"arguments": {
"query": "iphone 16 128",
"deliver_to_country": "CZ",
"limit": 2,
"offset": 0
}
}
}
Answer, HTTP 200, shortened
{
"deliver_to": "CZ",
"currency": "CZK",
"total_matches": 40,
"offset": 0,
"products": [
{
"slug": "apple-iphone-16-128-gb",
"name": "Apple iPhone 16 128 GB",
"match": "exact",
"match_note": null,
"total": 22990,
"recommended": true,
"currency": "CZK",
"goods": 22990,
"shipping": 0,
"shipping_known": true,
"in_stock": true,
"shops": 1,
"shop": {
"slug": "planeo-cz",
"name": "Planeo Elektro",
"country": "CZ",
"trust": "rated"
},
"captured_at": "2026-10-12T12:02:37Z"
}
],
"next_actions": [
{
"tool": "find_best_price",
"description": "Every offer of the first product with the verdict.",
"params": {
"query": "Apple iPhone 16 128 GB",
"deliver_to_country": "CZ"
}
}
]
}
find_best_price · Lowest product price for a query: verdict, the recommended offer with its source, shipping and capture time, every offer with its blockers.
REST
curl -s "https://fordeal.ai/api/v1/deals/best-price?query=Apple+iPhone+16+128+GB&deliver_to_country=CZ&locale=en"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_best_price",
"arguments": {
"query": "Apple iPhone 16 128 GB",
"deliver_to_country": "CZ",
"locale": "en"
}
}
}
Answer, HTTP 200, shortened
{
"product": {
"slug": "apple-iphone-16-128-gb",
"name": "Apple iPhone 16 128 GB",
"brand": "Apple",
"category": "mobily",
"variant": {
"id": "apple-iphone-16-128-gb",
"family_id": "line:apple-iphone-16",
"family_kind": "line",
"storage": "128 GB",
"ram": null,
"color": null,
"color_id": null,
"model": [],
"connectivity": [],
"size": null
},
"variants_url": "/api/v1/deals/products/apple-iphone-16-128-gb/variants"
},
"match": "exact",
"match_note": null,
"verdict": "buy_now",
"headline": "Buy now at Planeo Elektro for CZK 22,990 in total.",
"reasons": [
"at_90d_low"
],
"warnings": [
"The shop has customer ratings but no verified-shop badge."
],
"best": {
"offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
"shop": {
"slug": "planeo-cz",
"name": "Planeo Elektro",
"country": "CZ",
"trust": "rated",
"rating": 0.84,
"rating_source": "google",
"rating_captured_at": "2026-10-09T11:18:24Z"
},
"title": "Apple iPhone 16 128GB Black",
"source": "scrape",
"source_name": "planeo-cz-page",
"price": 22990,
"currency": "CZK",
"in_stock": true,
"condition": "new",
"delivery_days": null,
"unknown": [
{
"field": "delivery_days",
"reason": "not_stated"
}
],
"total": {
"deliverTo": "CZ",
"currency": "CZK",
"goods": 22990,
"shipping": 0,
"shippingUnknown": false,
"shippingApproximate": false,
"total": 22990,
"fx": null,
"crossBorder": false
},
"url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
"direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
"captured_at": "2026-10-12T12:02:37Z",
"age_hours": 21.6,
"stale": false,
"blockers": []
},
"offers": [
{
"offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
"shop": {
"slug": "planeo-cz",
"name": "Planeo Elektro",
"country": "CZ",
"trust": "rated",
"rating": 0.84,
"rating_source": "google",
"rating_captured_at": "2026-10-09T11:18:24Z"
},
"title": "Apple iPhone 16 128GB Black",
"source": "scrape",
"source_name": "planeo-cz-page",
"price": 22990,
"currency": "CZK",
"in_stock": true,
"condition": "new",
"delivery_days": null,
"unknown": [
{
"field": "delivery_days",
"reason": "not_stated"
}
],
"total": {
"deliverTo": "CZ",
"currency": "CZK",
"goods": 22990,
"shipping": 0,
"shippingUnknown": false,
"shippingApproximate": false,
"total": 22990,
"fx": null,
"crossBorder": false
},
"url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
"direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
"captured_at": "2026-10-12T12:02:37Z",
"age_hours": 21.6,
"stale": false,
"blockers": []
}
],
"hidden_risky_shops": 0,
"history": {
"days": 90,
"currency": "CZK",
"lowest": 22990,
"highest": 22990,
"points": [
{
"date": "2026-10-01",
"price": 22990
}
]
},
"deliver_to": "CZ",
"currency": "CZK",
"fx_date": "2026-10-12",
"data_source": "stored",
"refresh_pending": false,
"commission_disclosure": "When you buy through a Fordeal link, the shop pays Fordeal a commission. It does not raise your price and it never affects the order: offers are ranked by product price and shop trust only; shipping is shown separately for each offer."
}
get_product · The same card by product id, as the product page shows it.
REST
curl -s "https://fordeal.ai/api/v1/deals/products/apple-iphone-16-128-gb?deliver_to_country=CZ&locale=en"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_product",
"arguments": {
"product": "apple-iphone-16-128-gb",
"deliver_to_country": "CZ",
"locale": "en"
}
}
}
Answer, HTTP 200, shortened
{
"product": {
"slug": "apple-iphone-16-128-gb",
"name": "Apple iPhone 16 128 GB",
"brand": "Apple",
"category": "mobily",
"variant": {
"id": "apple-iphone-16-128-gb",
"family_id": "line:apple-iphone-16",
"family_kind": "line",
"storage": "128 GB",
"ram": null,
"color": null,
"color_id": null,
"model": [],
"connectivity": [],
"size": null
},
"variants_url": "/api/v1/deals/products/apple-iphone-16-128-gb/variants"
},
"match": "exact",
"match_note": null,
"verdict": "buy_now",
"headline": "Buy now at Planeo Elektro for CZK 22,990 in total.",
"reasons": [
"at_90d_low"
],
"warnings": [
"The shop has customer ratings but no verified-shop badge."
],
"best": {
"offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
"shop": {
"slug": "planeo-cz",
"name": "Planeo Elektro",
"country": "CZ",
"trust": "rated",
"rating": 0.84,
"rating_source": "google",
"rating_captured_at": "2026-10-09T11:18:24Z"
},
"title": "Apple iPhone 16 128GB Black",
"source": "scrape",
"source_name": "planeo-cz-page",
"price": 22990,
"currency": "CZK",
"in_stock": true,
"condition": "new",
"delivery_days": null,
"unknown": [
{
"field": "delivery_days",
"reason": "not_stated"
}
],
"total": {
"deliverTo": "CZ",
"currency": "CZK",
"goods": 22990,
"shipping": 0,
"shippingUnknown": false,
"shippingApproximate": false,
"total": 22990,
"fx": null,
"crossBorder": false
},
"url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
"direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
"captured_at": "2026-10-12T12:02:37Z",
"age_hours": 21.6,
"stale": false,
"blockers": []
},
"offers": [
{
"offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
"shop": {
"slug": "planeo-cz",
"name": "Planeo Elektro",
"country": "CZ",
"trust": "rated",
"rating": 0.84,
"rating_source": "google",
"rating_captured_at": "2026-10-09T11:18:24Z"
},
"title": "Apple iPhone 16 128GB Black",
"source": "scrape",
"source_name": "planeo-cz-page",
"price": 22990,
"currency": "CZK",
"in_stock": true,
"condition": "new",
"delivery_days": null,
"unknown": [
{
"field": "delivery_days",
"reason": "not_stated"
}
],
"total": {
"deliverTo": "CZ",
"currency": "CZK",
"goods": 22990,
"shipping": 0,
"shippingUnknown": false,
"shippingApproximate": false,
"total": 22990,
"fx": null,
"crossBorder": false
},
"url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
"direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
"captured_at": "2026-10-12T12:02:37Z",
"age_hours": 21.6,
"stale": false,
"blockers": []
}
],
"hidden_risky_shops": 0,
"history": {
"days": 90,
"currency": "CZK",
"lowest": 22990,
"highest": 22990,
"points": [
{
"date": "2026-10-01",
"price": 22990
}
]
},
"deliver_to": "CZ",
"currency": "CZK",
"fx_date": "2026-10-12",
"data_source": "stored",
"refresh_pending": false,
"commission_disclosure": "When you buy through a Fordeal link, the shop pays Fordeal a commission. It does not raise your price and it never affects the order: offers are ranked by product price and shop trust only; shipping is shown separately for each offer."
}
product_variants · The variants of the product with stable ids.
REST
curl -s "https://fordeal.ai/api/v1/deals/products/apple-iphone-16-128-gb/variants?deliver_to_country=CZ&locale=en"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "product_variants",
"arguments": {
"product": "apple-iphone-16-128-gb",
"deliver_to_country": "CZ",
"locale": "en"
}
}
}
Answer, HTTP 200, shortened
{
"slug": "apple-iphone-16-128-gb",
"family_id": "line:apple-iphone-16",
"family_kind": "line",
"axes": [
"storage",
"color"
],
"currency": "CZK",
"variants": [
{
"id": "apple-iphone-16-128-gb",
"slug": "apple-iphone-16-128-gb",
"current": true,
"storage": "128 GB",
"size": "128 GB",
"color": null,
"color_id": null,
"total": 22990,
"in_stock": true,
"url": "https://fordeal.ai/en/p/apple-iphone-16-128-gb"
}
]
}
price_history · Daily lowest price for 90 days and where each price comes from.
REST
curl -s "https://fordeal.ai/api/v1/deals/history/apple-iphone-16-128-gb?days=90¤cy=CZK"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "price_history",
"arguments": {
"product": "apple-iphone-16-128-gb",
"days": 90,
"currency": "CZK"
}
}
}
Answer, HTTP 200, shortened
{
"product": {
"slug": "apple-iphone-16-128-gb",
"name": "Apple iPhone 16 128 GB",
"variant": {
"id": "apple-iphone-16-128-gb",
"family_id": "line:apple-iphone-16",
"family_kind": "line",
"storage": "128 GB",
"ram": null,
"color": null,
"color_id": null,
"model": [],
"connectivity": [],
"size": null
}
},
"history": {
"days": 90,
"currency": "CZK",
"lowest": 22990,
"highest": 22990,
"points": [
{
"date": "2026-10-01",
"price": 22990
}
]
},
"offers": [
{
"shop": "Planeo Elektro",
"shop_slug": "planeo-cz",
"title": "Apple iPhone 16 128GB Black",
"price": 22990,
"currency": "CZK",
"condition": "new",
"source_name": "planeo-cz-page",
"in_history": true,
"captured_at": "2026-10-12T12:02:37Z"
}
]
}
compare_digital · Digital services by price per month, each with its official price list and check date.
REST
curl -s "https://fordeal.ai/api/v1/digital/compare?category=ai-chat&deliver_to_country=CZ"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "compare_digital",
"arguments": {
"category": "ai-chat",
"deliver_to_country": "CZ"
}
}
}
Answer, HTTP 200, shortened
{
"category": "ai-chat",
"currency": "CZK",
"fx_date": "2026-10-12",
"rows": [
{
"id": "claude-free",
"provider": "Anthropic",
"service": "Claude",
"plan": "Free",
"monthly": {
"amount": 0,
"currency": "EUR"
},
"monthlyLocal": {
"amount": 0,
"currency": "CZK",
"rate": 24.39,
"rateDate": "2026-10-12"
},
"sourceUrl": "https://claude.com/pricing",
"verifiedOn": "2026-10-05"
}
]
}
price_history · Unknown product: HTTP 404, error.code not_found.
REST
curl -s "https://fordeal.ai/api/v1/deals/history/no-such-product"
MCP tools/call (POST to the MCP endpoint)
POST https://fordeal.ai/mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "price_history",
"arguments": {
"product": "no-such-product"
}
}
}
Answer, HTTP 404, shortened
{
"error": {
"code": "not_found",
"message": "unknown product no-such-product",
"fix": "Use \`product.slug\` from a find_best_price answer."
}
}
/deals/search · A wrong parameter: HTTP 400, error.code validation with the list of issues.
REST
curl -s "https://fordeal.ai/api/v1/deals/search?query=iphone&limit=abc"
Answer, HTTP 400, shortened
{
"error": {
"code": "validation",
"message": "invalid request: limit: Invalid input: expected number, received string",
"fix": "Fix the listed fields. GET /api/openapi.json documents every parameter.",
"details": {
"issues": [
"limit: Invalid input: expected number, received string"
]
}
}
}
/deals/shops/compared · Over the limit: HTTP 429 with Retry-After.
REST
curl -s "https://fordeal.ai/api/v1/deals/shops/compared?country=CZ"
Answer, HTTP 429, shortened
{
"error": {
"code": "rate_limited",
"message": "rate limit of 10 requests per minute reached",
"fix": "Wait 42 s and retry (Retry-After). Without an API key the limit is 10 requests per minute per IP address; generate a free key at https://fordeal.ai/agents#klic and send Authorization: Bearer <key> for 60 per minute.",
"details": {
"limit_per_min": 10,
"retry_after_seconds": 42,
"window_seconds": 60,
"limit": 10,
"remaining": 0,
"reset": 42,
"reset_at": "2026-10-28T09:15:00.000Z",
"anonymous": true,
"get_a_key": "https://fordeal.ai/agents#klic"
}
}
}
Paging, limits, errors and unknown values
Paging
| search_products and GET /deals/search | limit (1 to 100, default 20) and offset (default 0); total_matches counts every match before paging. |
|---|---|
| GET /deals/products | limit up to 500 and offset; total counts the matching products. facets=true adds brands, shops, price range and attribute values over the whole filtered list. |
| A page past the end returns an empty list with the same total. |
Limits
| Without a key | 10 requests per minute per IP address, MCP tool calls and REST together. |
|---|---|
| With a key | 60 requests per minute. |
| Over the limit | HTTP 429 with a Retry-After header in seconds, error.code rate_limited and error.details.retry_after_seconds, over MCP too. |
Errors
- Every error has the shape {"error":{"code","message","fix"}}: code is stable and machine-readable, fix says what to change.
- validation 400 (details.issues lists the wrong parameters), country_not_supported 400, invalid_input 400, unauthorized 401, forbidden 403, not_found 404, rate_limited 429, not_available 503.
- Over MCP an error is a tool result with isError: true and the same body in structuredContent.
Unknown values, estimates and stale data
| A value we do not know is null and says why: each offer lists unknown[] (delivery_days not_stated, shipping not_stated or approximate, shop_rating unrated). | |
|---|---|
| total.shippingUnknown true | the total is the goods price only and the offer is never best; total.shippingApproximate true: shipping is the shop's lowest stated rate, an estimate. |
| Every offer carries captured_at and age_hours; stale is true after 36 hours and such an offer is never best; refresh_pending is true while prices are being read again. | |
| match close with match_note | the product is the nearest variant, not the one asked for; product.variant and product_variants give the exact ids. |
| history.since is the first day with data | a 90-day window may hold fewer days. |
Answer fields, estimates and pages
- labels on every offer, the same words the website prints: lowest_price only on the lowest product price among the new offers shown; recommended on the trust-recommended offer when it is not the lowest product price (never call it the cheapest); lowest_verified_total on the cheapest total with a stated (not "from") shipping when it is not the lowest product price.
- shipping_is_estimate true: the shipping is only a "from" rate or unknown, so the total is a lower bound; saving_is_estimate true (an offer's savings_vs_best, recommended_surcharge): the difference rests on such a shipping. Say "estimated saving at the stated minimum shipping", never a certain saving.
- saving_kind is always "estimate" where a saving or difference is stated (an offer's savings_vs_best, recommended_surcharge, a cross-border saving, an energy saving_year): it is a difference at the prices and shipping captured on the days in saving_basis, never a guaranteed result. Write "estimated saving" and name the capture date, not "you save".
- price_verdict {level low|usual|high|short_history|stale, percentile, days, basis} on find_best_price, get_product and price_history rates the latest price against the last 90 days of our own captured daily lows. Under 14 days of history it makes no judgement (short_history); it is never a discount claim.
- daily_deals and GET /deals/daily list the biggest measured drops of the last 24 hours at rated shops, spread over shops and categories (max_per_shop, the website asks 4; also category, country, min_percent); the pool for Slovakia holds the euro shops that deliver there.
- report_issue and POST /deals/issues take the offer_id of the offer in question (from the card), so a wrong price or variant of one row reaches the person who reads the queue with that row; the website has the same report control on every offer row.
- The pages "cheapest X" (/nejlevnejsi/<model>) and "X vs Y" (/srovnani/<a>-vs-<b>) have no endpoints of their own: they read GET /deals/products (query, category, slugs, deliver_to_country; search_products, product_variants), and compare_digital and compare_mobile for services and operators. Ask the same question with the same tools.
- Links to a provider on a /digitalni comparison go through /go/plan/<id>, a counted redirect (plan key, page type, our own page; nothing personal; robots flagged). GET /deals/plan-clicks/{kind}/{id} (kind plan|insurance|mobile) returns the provider URL without counting; an offer's own link is its url (/go/<shop>/<offer_id>).
- GET /deals/coverage (per shop) and GET /deals/coverage/groups (per category group) give today's coverage: products with a stored price, shops pricing and shops waiting for a feed. The numbers change daily, so read them instead of quoting a figure from a document.