Fordeal

Deletes the watch behind a token from any watcher e-mail (confirmation or alert). The row is gone at once; the token stops working.

Deletes one of the signed-in person's saved comparisons; its share link stops working.

Deletes one of the signed-in person's lists with its products; its share link stops working. Another id answers not_found.

Deletes one of the signed-in person's watches; no more mails for it. Only the token's own watches; another id answers not_found.

Removes a product or a digital plan from the signed-in person's favourites. `removed: false` when it was not there.

Removes a product from one of the signed-in person's lists; `removed: false` when it was not there. Another person's list answers not_found.

Creates (or resets) the signed-in person's watch of one product (one per product). Fordeal mails the person when the recommended total for `deliver_to_country` (goods + shipping, same meaning as on the website) falls under `target_total`, never twice for one price and at most once a day. Without `target_total` the target is today's total: the mail comes when the price really drops (by the currency's step, e.g. 50 CZK). Today's total is stored as saved_total. Needs the person's access token. Answers the watch as list_my_price_watches shows it.

`shared: true` makes a read-only link (a new random token; an older link stops working); `shared: false` removes the link. The link shows the plans at today's prices and the name, never the owner.

Changes one of the signed-in person's lists: `name` renames it; `shared: true` makes a read-only link (a new random token, an older link stops working), `shared: false` removes the link. The link shows the list's name and products at today's prices, never the owner, the notes or the saved prices. Another id answers not_found.

Changes one of the signed-in person's watches: `paused: true` stops the mails until `paused: false`; `target_total` sets a new limit (null = any real drop under the saved total). Only the token's own watches; another id answers not_found.

The /kontakt form without the website: `name`, `email` (where the answer goes), `topic` general | support | cooperation | privacy and `message` (10 to 4 000 characters). The message goes as one notice to hello@fordeal.ai with the sender as Reply-To; a person answers by e-mail. The sender gets no automatic e-mail (the answer here is the confirmation of receipt, with `id`). The same message twice on one day answers the same id with `duplicate: true`. A shop that wants to be compared uses register_shop; a partner, the media or a creator may use send_cooperation_inquiry for a structured request. Public, no key; five messages a minute per caller.

The cooperation forms (docs/texty/formulare.md 2–4) without the website. `kind` partner (an affiliate network, a feed provider or a technical integration: organization, website, markets as ISO codes, cooperation_type affiliate | feed | integration | other, message = the offer and its terms), media (name, organization = the newsroom, message = the topic or the information needed, optional deadline YYYY-MM-DD and links) or creator (name or channel, website = the main channel, topic = the content's topic and audience, message = the idea, optional links: other channels, media kit). A shop that wants to be compared uses register_shop instead. A person reads every message; the sender gets a confirmation of receipt (not an approval) and the operator one notice. The same message twice within a day answers the first id with duplicate true. Public, no key; five messages a minute per caller. 503 not_available until migration 0065 is applied.

Adds a product (by slug) to one of the signed-in person's lists with an optional private note; the product's total for `deliver_to_country` today is kept as saved_total (for "the price changed since you saved it"). Adding it again only changes the note. At most 200 products per list. Another person's list answers not_found.

What a month of AI API use costs per bill item for every model we compare (or one provider / chosen models): fresh input, input read from the cache, input written into the cache, output, and the total, per request and per month in the price list's currency (USD) and in the buyer's currency by the Czech National Bank rate (fx_date), each item's whole-percent share, every other item the price list names (batch discount and whether it applied, the dearer long-prompt band and whether the request is in it, the context window, cache_write_not_stated when the price list names no write price and writes were billed as ordinary input), what is included, and the official source_url with verified_on. Default scenario: 1 000 requests a month, 1 500 input and 600 output tokens each, 40 % of the input read from the cache and 10 % written; every field can be changed. Nothing is estimated beyond the stated prices.

Products whose cheapest total (goods + shipping + FX to `deliver_to_country`) comes from a shop abroad and beats the cheapest domestic offer, with the saving in the deliver-to currency (`saving_kind: "estimate"`: the difference at the prices and shipping captured at `captured_at`, with `saving_basis`; present it as an estimate, never a guaranteed result). Cross-border offers carry EU warranty and returns but support may be in another language; find_best_price shows the `cross_border` block for one product.

Before or instead of registering: reads one product feed and answers whether Fordeal can use it. Give the feed's public address in `feed_url` (read through the SSRF guard: public hosts only, FordealBot, robots.txt respected, 20 s cap) or the file itself in `feed_content` (XML or CSV text, at most 8 MB) or `feed_base64` (a gzip-packed file; ZIP is refused), plus the shop's delivery `country` and, with a file, its `domain`. The answer: health ok | warn | fail, counts (items, skipped, with EAN, price, picture, availability, shipping, category), coded issues (no_items, items_skipped, feed_unreadable, price_zero, currency_mismatch, url_not_shop_host, duplicate_item_id, encoding_suspect, price_outlier, missing_ean, availability_unknown, shipping_missing, image_missing, category_missing, stale_feed) with the first affected items by the shop's own id and name, `blocking` = the error codes to fix first, `validation` = the required-field check (title, price, URL, EAN) in Czech sentences for Heureka, Zboží, Google and CSV feeds, and `preview.shown` = the first items as the comparison would show them (goods price, shipping to the country from the feed, total, stock, picture, what each lacks). Nothing is stored and nothing is mailed. A feed that cannot be read answers health fail with `read_error` {code, message, fix}. Next: register_shop with the same feed. Public; ten checks a minute per caller.

The double opt-in click: the confirmation token from the first watcher e-mail turns the watch on. Only the person who received the e-mail holds the token.

Creates an empty private list (e.g. Narozeniny, Nová kuchyň) in the signed-in person's account; add products with add_to_list. At most 50 lists per person.

Discounts at rated shops today, biggest absolute saving first: with 30 days of our own history for the offer, the discount is measured only against its lowest price in the 30 days before the reduction (EU Omnibus, CJEU C-330/23; discount_basis "lowest_30d", price_before = lowest_30d); until that history exists, only against the old price the shop itself states (discount_basis "shop_stated", not verified by us, at most 50 %). Never an average or other shops' prices. For one country, optionally one category of any level and a minimum percent. for one country and optionally one category slug (from the deal categories). Shops on a risk list and shops without a rating are never included. Each row carries the current price, the previous price, the drop, the shop with its trust label and the capture time. Next: find_best_price with the product name for the full comparison.

Every recorded change of a digital plan's price, newest first: plan_id, verified_on (the day it changed), from and to (price and currency), source (person = confirmed against the official page in our review; catalog = the stored price list changed between two daily snapshots) and source_url. Recording started on tracking_since; nothing before it is known and nothing is back-filled, so an empty list means no change since tracking_since. An unchanged price renewed by the daily check is no change. Filter by plan (the id from /digital/plans).

Development of household electricity and gas prices per kWh (Czechia), as published by Eurostat (semi-annual, all taxes and levies included, the most common consumption band), with the dataset link and the day it was fetched; never interpolated. Our own price-list readings start on own_history_since and are not yet a series. Use energy_unit_prices for today's price from the current price lists.

Facts from the suppliers' official price lists (verified: false: the yearly calculation built on them is not yet checked by an independent expert; estimate_note gives the sentence and the day of the price lists). Every household electricity and gas supplier of a country we know of (Czechia: 46), or one supplier with `id`: its official price-list page, whether we priced it (status priced | gap with the reason), its products with the prices of the official price lists (electricity: commodity price per MWh by rate and the monthly fee; gas: price and fee by consumption band; all without VAT, with source_url, valid_from and verified_on), whether each price is fixed and until when, and the bill guide (bill_guide: the customer portal and the steps to find and download the bill, from the supplier's own help page). Former suppliers (e.g. Bohemia Energy) are listed with what happened to their customers. No contract can be signed here and no link earns a commission.

An indicative calculation, not yet checked by an independent expert (verified: false); show estimate_note with the result. Price of one kWh with VAT for households of a country (Czechia for now), per distributor area, computed only from the energy regulator's tables and the suppliers' official price lists we read: regulated_kwh (variable regulated part: distribution of the rate, system services, renewables support, tax; the same with every supplier), supplier_kwh (commodity price: min, median, max over the priced offers), marginal_kwh (regulated + supplier: the cost of one more kWh, what an appliance costs to run) and all_in_kwh (the yearly total for `mwh` with every fixed fee spread over its kWh). Electricity for one rate (default D02d) and 2.5 MWh a year by default; gas for 9 MWh a year by default. Spot and formula prices are never counted. Use estimate_appliance_energy for an appliance's yearly cost.

An estimate (verified: false, estimate_note with the day of the prices). kind fridge: label_kwh_year from the EU energy label (kWh/annum). kind washer: kwh_per_100_cycles from the EU energy label and washes_per_week (default 4). kind heating: area_m2 and heat_need_kwh_m2 (specific heat need for heating from the building's energy performance certificate; references: passive house 20, low-energy house 50 kWh/m² a year by ČSN 73 0540-2), source direct | heat_pump | gas_boiler with scop (heat pump, default 3) or efficiency (gas boiler, default 0.9). Answers kWh a year and the yearly and monthly cost at the price of one more kWh (median marginal price in the distributor area from energy_unit_prices, or price_per_kwh if given); `defaults` names every value that was assumed.

An information comparison, not a ranking (prices: false, ranking: false, score: null): Fordeal is not an insurance intermediary, sells no insurance, shows no premium and recommends no policy. For a country (CZ for now) it answers the kinds of insurance (motor third-party liability, comprehensive motor, home contents, property, travel, personal liability, accident, life, legal protection, health insurance for foreigners, other) with the four things to compare besides the price, and `cards`: one per insurer with the kinds its public site offers, the products in the insurer's words (products: name, kind, online), the kinds that can be concluded online on the official site (online_kinds; online_unknown_kinds = the site does not say), a nonstop assistance line, a mobile app and an online claim form, each a fact {value: true | false | null, note, source_url, checked_on} where null means the site does not state it (never a no), the IČO from the ČNB register (registry; cross_border: true for an offer without a Czech IČO), the public customer rating (source: Firmy.cz or Google Maps by its link; score, scale, count, source_url, fetched_on; only from 10 reviews, otherwise null = no rating yet), factual tags and the official website (commission: false, affiliate: false, no tracking parameters). Filters: kind, online (online for the asked kind), assistance, app, claim_online (true); filter_counts says how many insurers each option leaves. sort: name (default, alphabetical) | rating (public rating from the highest, insurers without a rating last) | kinds (number of kinds offered). compare = 2–3 insurer ids for `comparison` side by side. Tell the person to read the terms on the insurer's site; the premium and the contract are the insurer's.

Daily lowest price of a product across compared shops for up to 365 days (the last point, today, is the product price the product page shows as its main price), plus every current offer with its capture time. `product` is the slug from find_best_price (`product.slug`) or a product id. Use it to say whether today's price is a low, and how much it moved. `price_verdict` {level low|usual|high|short_history|stale, percentile, days, basis} rates the latest price against the last 90 days of our own captured daily lows (no judgement under 14 days; never a discount claim); find_best_price carries the same object. Next: find_best_price for the current recommendation.

The rows the website shows above the full product list (/produkty) for a buyer country, each a list of up to 12 products with the same summary fields as search_products: `deals` (today's price drops; discount against the offer's lowest price of the 30 days before the drop when 30 days of its history exist, else against the shop's own stated price; never an average), `trending` (trend = (1 + interest) × 0.5^(age_days / 14), interest = searches, product-page views and shop clicks of the last 30 days, age = days since the product entered the catalogue; 2+ shops only) and the seasonal rows of the buyer country's calendar (Black Friday, Christmas gifts by budget and for whom, Valentine's, Mother's Day, Father's Day, back to school, summer), e.g. `christmas:budget-500` or `christmas:for_her`. No product stands in two rows, one shop is behind at most 3 cards of a row, a row under 4 products is left out. `formulas` states every rule; `seasons` the active windows. `date` (YYYY-MM-DD) reads the calendar of another day with today's products. Next: get_product with a product slug for the full comparison.

The variants of one product, each with a stable `id` (its product slug), `current` (true for the one asked for, always listed), storage, size, colour and `color_id`, its lowest total for `deliver_to_country` and stock. `family_id` names the set (a garment's item group, or the model line `line:<words>`), `axes` says what tells them apart. Use it to switch from a card to the exact variant the buyer asked for, then get_product with that id. A product without siblings answers itself only. Mirrors GET /api/v1/deals/products/{slug}/variants.

One call registers a shop (P01): name, domain, delivery country, contact e-mail, the feed (its address in `feed_url`, or the file in `feed_content` / `feed_base64`), how commission is paid and the accepted partner terms version. An address is read at once through the SSRF guard (public hosts only, 422 url_rejected otherwise) with a 12 s cap; a file is decoded (at most 8 MB, gzip allowed, ZIP refused: 422 upload_zip_unsupported, 413 upload_too_large) and only its sha-256 and size are kept. Either way the feed is diagnosed (P04) and the 202 answer carries `feed.health` ok | warn | fail with the top three issues; the full report is stored on the request, `feed_source` says url or upload. One open request per domain: a second call updates it and answers the same id with `duplicate: true`; a declined domain may register again. The contact gets the `shop_registration_received` mail (its language: `locale`, else the country's default) with the confirmation link and the status page; the operator gets one notice. `verification.ownership` carries the token for the meta tag or file proof (verify_shop_domain). A shop on the ČOI / SOI risk list is refused (403). A registration never lists a shop by itself: the operator decides. A shop registered with a file only is listed as still being added until it sends a feed address. Follow it with get_shop_registration. Six calls a minute per caller.

A notice under Article 16 of the Digital Services Act that content on fordeal.ai is illegal (a user review, product information, an offer, an image or anything else). Give `content_kind` review | product_info | offer | image | other, the `page_url` of the content (and the `product_slug` when it is on a product page), an `explanation` of why the content is illegal (20–4000 characters), the notifier's `name` and `email`, and `good_faith: true` confirming the notice is accurate and complete to the best of the notifier's knowledge. A person reviews every notice; the e-mail gets a confirmation of receipt at once and the decision later. For a wrong price or variant use report_issue instead. Public, no key; the anonymous rate limit applies.

When an offer on a product page is wrong (the shop's page shows another price, the offer is another variant or product, the link leads to the wrong shop or page, or anything else), file a report: `kind` price | variant | category | shop | other, `product_slug` (the stable product id from find_best_price or search_products), the `offer_id` of the offer (from the card's offers; optional) and a `message` saying what you saw (at most 1000 characters). An optional `email` gets the founder's answer; it is never shown. Every report goes to a queue a person reads; the same report sent twice within a day answers the first id with duplicate true. Public, no key; the anonymous rate limit applies.

Saves 2 to 4 digital plans (plan ids from compare_digital / compare_mobile) as a private comparison in the signed-in person's account. Private: nobody else can open it until share_comparison makes a link.

Adds a product (kind product, `id` = slug) or a digital plan (kind digital, `id` = plan id from compare_digital or compare_mobile) to the signed-in person's favourites. Saving twice changes nothing.

The products the home page's first row shows, found by the data and not by a list of model names: new products people look for, up to 12, each a summary like search_products (total price with shipping at a rated shop, shops, in stock, capture time) plus `trending` with `score`, `parts` (the points of generation, newness, interest, gsc, growth, keyword, seed) and `raw` (model number and its place among the line's generations, days since the family entered the catalogue, decayed interest, Search Console weight, shops that started to list it, variants). A product qualifies when its model number is the newest or the one before in its line (iPhone 18 against iPhone 17), or its model family entered the catalogue in the last 75 days, and someone searched for it, clicked to a shop, found it on Google or a shop started to list it; the score adds model generation 40, newness 10, searches (halved every 7 days over 28 days) and human clicks 25 × log2(1 + n), Search Console 15 × log2(1 + n), new shops 12 × log2(1 + n). Colours and capacities are one card (the cheapest variant); at most 4 cards per category, 3 per brand and 3 per shop. Only products with two or more shops, a rated shop with known shipping and a price in stock; a shop on the ČOI/SOI risk list is never shown. Recomputed by the worker each night; `generated_at` says when, null before the first run. Next: get_product with a product slug for the full comparison.

After register_shop: publish <meta name="fordeal-verification" content="TOKEN"> on the shop's home page, or the token as the whole content of https://DOMAIN/fordeal-verification.txt, then call this with the domain and the token from `verification.ownership`. One request to each address with Fordeal's identified bot (www. and the bare host). The answer: ok with the method (meta | file, or already), or `error.code` not_found (no request with this domain and token) | not_verified (neither place carries the token; a CDN cache may take minutes). Proving the domain marks the request as confirmed, like the e-mail link; the operator still decides. Public.

A household gives its e-mail and the last day of its fixed electricity or gas price (fixation_end YYYY-MM-DD, today to 5 years ahead); optionally the distributor area, today's supplier (supplier_id from energy_suppliers) or product (current_offer_id from compare_energy products) and the consumption. Double opt-in: the e-mail first gets a confirmation link and nothing else is sent before the person clicks it (an agent cannot confirm for the person). A confirmed watch gets one e-mail 45 days before the end with the offers cheaper for its need (from the official price lists; an estimate). Every mail has a cancel link. Unconfirmed watches are deleted after 7 days, every watch 30 days after its end date. No account, no contract, no commission. At most 5 watches per e-mail. Ask the person for consent before passing their e-mail.

Prices of digital services for a buyer's country, cheapest first, from the providers' official price lists (each row has source_url and verified_on) converted to the buyer's currency by the Czech National Bank rate (fx_date). Categories: ai-chat (ChatGPT, Claude, Gemini, Copilot, Perplexity, Grok, Mistral Vibe, GitHub Copilot, Cursor, Jasper, DeepL… subscriptions), ai-api (price per 1M input and output tokens of the main models: OpenAI, Anthropic, Google, Mistral, xAI, DeepSeek, AI21, Amazon Nova), ai-creative (Midjourney, Runway, Kling, Leonardo, Canva, Firefly, ElevenLabs, Suno… per month, per picture or second of video when stated), streaming, music, vpn, cloud, office (Microsoft 365, Google Workspace, Zoho, Notion, Slack, Zoom… personal, family and business per user; business prices usually exclude VAT), creative (Adobe Creative Cloud, Canva, Figma, CapCut, DaVinci Resolve Studio… monthly, yearly or a one-time purchase: such a row has oneTimeLocal instead of a monthly price), passwords (1Password, Bitwarden, Dashlane). `usage` turns the list into a cost of that use: for ai-api messages_per_month (+ input_tokens and output_tokens per message, default 1 500 and 600) (+ cache_share 0–1 and batch) gives usage_cost a month, usage_breakdown (input, cached input, output; whether the long-prompt band or the batch discount applied) and break_even_messages (below it the API is cheaper than the provider's cheapest paid chat plan); for ai-creative images_per_month and video_seconds_per_month. A null price means the official page did not show one; it is never guessed. Each row carries data_location from the provider's own privacy policy (controller, storedIn country codes, inChina, authoritiesClause, quote, url, checked), null when we have not read it. Where the same plan is also sold inside the app (inAppPrices: the App Store's price for the buyer's country, with VAT, verifiedOn and sourceUrl), inApp compares a month on the web (the price list's price, plus the country's VAT when the list excludes it: web.vatAdded) with a month in the app, both in the buyer's currency: cheaper (web | app | same) and difference a month; inAppYearly does the same for yearly billing. Say both prices and which is cheaper; a plan without inApp has no store price read (never assume the app costs the same). Every row carries price, the one amount to show (the same as fordeal.ai shows): price.monthly and price.yearly (12 × monthly; yearlyWhenYearly = 12 × the month paid yearly) in the buyer currency with the buyer country VAT added where the price list excludes it (price.vat: included | by_law | added | excluded | unknown, price.vatRate), price.billing, price.channel (web) and price.rateDate; rows are ranked by price.monthly. promo (an open promotion) has monthlyLocal as converted and monthlyLocalGross on the same VAT basis as price: show the gross one, then price.monthly after it, both with the VAT word of price.vat. kind says who can buy the plan: regular (anyone), student (verified students or educators), business (companies and teams) or promo (only under the offer terms); never present a non-regular plan as the generic cheapest without saying who is eligible.

An indicative calculation, not yet checked by an independent expert (verified: false): present the result as an estimate, never as a guaranteed price; show estimate_note (the sentence with the day of the data, in `locale` cs | sk | en) with every result. Household electricity and gas offers (Czechia for now) ranked by the yearly bill for a stated consumption in one distributor's area, with VAT. The bill is split into the regulated part (distribution, system services, renewables support, market operator, tax: set by the energy regulator for the distributor, the same with every supplier) and the supplier part (commodity price and monthly fee: what switching changes). Every offer has the supplier's official price list (source_url, verified_on, valid_from) and says whether the price is fixed (fixed_months or fixed_until) or variable. Spot and formula prices are never ranked; they are listed in not_ranked. Offers whose price list was read only for another distributor's area are left out. Electricity: distributor (cez-distribuce | egd | pre-distribuce), rate (D01d, D02d, D25d, D26d, D27d, D35d, D45d, D56d, D57d, D61d), mwh = yearly high-tariff (or all) consumption, nt_mwh = low-tariff consumption; breaker = main breaker (1x25, 3x10, 3x16, 3x20, 3x25 default, 3x32, 3x40, 3x50, 3x63; it sets the fixed monthly distribution price from the regulator's table); postcode (5 digits) instead of distributor picks the distributor area as an estimate (area.estimate = true; two candidates when the postcode spans an area boundary: then pass distributor). Every result is an estimate (result_type: estimate, guaranteed: false): the binding bill depends on the actual consumption, the distributor stated on the bill and the contract. Gas: distributor (gasnet | gas-distribution | ppd), mwh = yearly consumption up to 63 MWh; postcode instead of distributor picks the gas area the same way (estimate; two candidates around Prague or on an area boundary: then pass distributor). Call without a distributor to get the distributors, rates (rate_info: low-tariff hours a day), products and the regulated price tables. COMPARISON TEMPLATE (20 Oct 2026): every ranked offer carries the forDeal score 0–10 (score, score_parts price / conditions / rating, score_weights as used, score_missing when a part is absent), labels (cheapest = lowest total of the list; best_value = highest score), a one-sentence reason, conditions (fixation months and bucket, term indefinite | fixed_term, notice_months, termination_fee none | stated, green; null = the price list does not state it) and the supplier's public rating (source, score, scale, count, source_url, fetched_on; counted only from 10 reviews; null = we have none, and the weights are renormalised, the answer says so). Filters: fixation none | 12 | 24 | 36 (variable price, or fixed up to 1 / 2 / 3+ years), pricing fixed | variable | spot (spot = market-price products, listed without a total), green true, no_penalty true (no fee for leaving stated); filter_counts says how many offers each chip would leave. sort score (default) | price. compare = up to 3 offer ids: the answer adds comparison with the same parameters side by side. Method and weights: scoring. What the household pays today, best first: current_offer (an id from products), or its own prices current_vt_price + current_nt_price + current_fee_month (current_prices_vat), or current_monthly (the advance); each offer then carries saving_year against it and the answer states saving_basis (offer | own_prices | advance) and warnings (e.g. nt_mwh_missing for a two-tariff rate without low-tariff consumption).

An indicative calculation (verified: false, with estimate_note like compare_energy). Pass the values from the household's electricity or gas bill (as read by POST /api/v1/digital/energy/bill, by yourself from the document, or typed by a person) and get the same ranked answer as compare_energy: yearly totals of every priced offer for that distributor area, rate and breaker, with the saving against the bill's own prices (saving_basis: own_prices) or against the monthly advance. Consumption of a billed period other than a year is scaled to 365 days by period_days. Confirm the values with the person before calling; nothing is stored.

Compare provider-level home internet summaries from docs/data/internet.json. Filter by country, technology, advertised speed, listed monthly price, commitment duration, or provider; sort by price, indicative price per advertised Mbps, or speed. Each result includes the provider's address-availability checker and source links. This source contains summarized ranges, not individual address quotes; unknown values stay null, and availability must be confirmed with the provider.

Compare the sourced CZ and SK mobile tariff records in docs/data/mobilni-tarify.json. Filter by country (required), operator, minimum data, unlimited calls, commitment, eSIM and 5G; legacy needs filters for minutes, SMS, no commitment and EU roaming also work. Sort by listed monthly price or the sourced price per GB. Every result includes its source URL, checked date and quote. Unknown values remain null and never satisfy positive filters.

The watch behind a token from a watcher e-mail (the `t` of the link): status pending | confirmed, the end date, the day of the alert, the e-mail masked. Answers not_found when the watch was cancelled or deleted.

Where to buy a product cheapest today: offers ranked by the real product price (converted to the buyer's currency with a dated rate), the shipping to the buyer's country shown as its own value on every offer, and whether the shop can be trusted. `sort=total` (or include_shipping=true) orders by goods + shipping instead. `query` is free text ("washing machine under 12 000, 60 cm"), a model name, an EAN, or a product URL from any e-shop. Returns one card: `match` (exact | close: close means the nearest product is another variant than the query names, e.g. iPhone 16 Plus for "iPhone 16 256 GB"; `match_note` says how, `warnings` opens with it and `reasons` carries close_match; never present a close card as the asked-for item), verdict (buy_now | wait | buy_alternative | no_offer) with a headline and explanation in `locale`, the recommended offer `best` (shop, trust label verified | rated | unknown, rating 0-1, total.goods = the product price and total.shipping in the deliver-to currency, total.total = their sum, FX date, capture time), `cheapest_total` (the offer with the lowest total including shipping), three alternatives (cheapest domestic, cheapest cross-border, best rated), every shown offer with its blockers and `price_status` (verified = goods + stated shipping, the sum the buyer pays; estimate = the shop states only its lowest "from" shipping rate; incomplete = shipping to the country unknown or import duties open, a lower bound that is never the cheapest), a 90-day price history, and `commission_disclosure`. Every offer carries `labels` (lowest_price = the lowest product price; recommended = `best` when it is dearer than that, never call it the cheapest; lowest_verified_total = the cheapest total with a stated, not "from", shipping), `shipping_is_estimate` (a "from" or unknown shipping: the total is a lower bound) and `saving_is_estimate` (its `savings_vs_best` rests on such a shipping: say estimated, never a certain saving). Rules: a shop on a consumer-protection risk list is never shown; a shop without a rating is never `best`; an offer with unknown shipping or a price older than 36 hours is never `best`. Cross-border offers carry `cross_border` (EU warranty, returns, support languages). Send the buyer to `best.url` (Fordeal's click URL, which forwards to the shop) and tell them the product price, the shipping and the capture time. Next: price_history for the trend, or find_best_price again with verified_only=true.

The same card as find_best_price and the website's product page /{locale}/p/{product}, for a product id you already hold (`product.slug` / `product.variant.id` from search_products, find_best_price or product_variants), without reading a query: no risk of landing on another variant. `product.variant` names the variant (storage, colour, model words, connectivity, size, `family_id` shared by its siblings). Answers from stored prices with the rule-based verdict; every offer carries `source_name`, `captured_at`, `blockers`, and the card `reasons` and `warnings`. An unknown id is `error.code` not_found. Next: product_variants for the other capacities or colours, price_history for the trend.

The report of a compared shop's last feed read (P04): health ok | warn | fail, counts (items, with EAN, price, picture, availability, shipping, category), and coded issues (no_items, items_skipped, feed_unreadable, price_zero, currency_mismatch, url_not_shop_host, duplicate_item_id, encoding_suspect, price_outlier, missing_ean, availability_unknown, shipping_missing, image_missing, category_missing, stale_feed) each with a count, a share and the first five affected items by the shop's own item id and name. Public: no feed address, no item links (the partner's signed-in view at GET /api/v1/partner/feed-diagnostics carries the item links). `error.code` not_found when the shop is unknown or has no feed run yet. For a feed that is not compared yet use check_shop_feed.

What happened to a registration (register_shop answers `id`; the id is the key, nothing else is needed): status diagnosing | received | approved | rejected | active, whether the contact confirmed, the decision with its reason and when, where the feed came from (`feed_source` url | upload, and the upload's fingerprint), the public feed report (health, summary, counts, the first issues without item links), `next` = what happens now, and the shop's page once it exists. The contact e-mail and the feed address are never returned. Older requests of the feeds-job flow answer their own statuses (pending, feed_found, …). Public.

How many people Fordeal sent to the shop in a window of UTC days (`from`/`to` YYYY-MM-DD, both included; the last 30 days by default, at most 366): the total, every day (zero days included), per delivery country and per channel (web | mcp | api | social). Only counted clicks of people from click_log: robots and the partner's test clicks are left out and reported in `excluded`; no orders or revenue are estimated (own-programme orders are in the partner portal). `truncated: true` when the window held more than 50 000 rows (the numbers are then a lower bound). Needs the signed-in person's Supabase access token and a shop of list_my_shops; another shop answers 403.

Coupon codes and promotions of compared shops, valid today, from the affiliate network eHUB (refreshed every 3 hours; never from newsletters or e-mails, never a shop on a risk list). For one country (the shop's country), the soonest ending first. Each row: the shop, `type` voucher (has a `code`) | action (no code), the advertiser's `title`, `discount` read from it (percent or amount with currency; `up_to` = "up to"; null when the text states no size of the discount, never a guess), `min_order` {amount, currency} when the text names a minimum order ("nákup nad 1 000 Kč"; it is never the discount), `valid_from`, `valid_until` (a date = the whole day), `url` the network's tracked link (Fordeal earns a commission on a purchase through it; the ranking never depends on it), `image` the card photo with `image_source` "shop_product" (a product of the shop's own offers in its main `category`) or "category" (our picture of that category; null = none, show `logo_url`), and `fetched_at` of the list. Next: find_best_price with a product name to compare the shop's prices.

Comparisons the person saved (2 to 4 digital plans each), newest first, with the page address and, when the person chose to share one, its share link. Private unless `shared: true`.

Products (kind product, by slug, with the total saved at that time) and digital plans (kind digital, by plan id) the person saved with the heart, newest first. Needs the person's access token. Live prices: search_products / compare_digital.

Every named list of the person whose Supabase access token is sent (Authorization: Bearer <token>; an agent API key is refused), oldest first, each with its products (newest first, the private note and the total saved at that time), and the share link when the person chose to share it. The heart's favourites are separate: list_my_favorites. Live prices: GET /api/v1/deals/products?slugs=.

Every price watch of the person whose Supabase access token is sent (Authorization: Bearer <token>; an agent API key is refused). Each row: id, product, status (active | paused), target_total and saved_total (the total when the watch was set or of the last alert; alerts fire only below it), the delivery country and currency, last_alert_at and `current` = today's total for that country (goods + shipping, shop, captured_at; recommended: false when no offer passes the trust rules). Next: update_price_watch to pause, resume or change the target, delete_price_watch to cancel.

The shops whose numbers the signed-in person may read: a contact of a shop in Fordeal's own affiliate programme whose partnership the operator approved and whose domain is proven (`access: partner`; a pending partner sees nothing here), or the contact e-mail of a registration the operator approved (`access: registration`). Needs that person's Supabase access token (Authorization: Bearer <token>, the website holds it after the e-mail sign-in link); an agent API key is refused. Each row: slug, name, domain, country, status, access, the shop's page. Next: get_shop_statistics with a slug.

The shops whose prices flow today for a delivery country (with their rating 0..1, rating source and trust label) and the shops still waiting for their feed. Use it to answer "can I trust shop X" or "do you compare shop Y".

The website's category and search grid for an agent: products with the product price of their shown offer (`lowest_goods`, in the `deliver_to_country` currency; its shipping `lowest_shipping` and the total `lowest_total` beside it, with capture time and `price_status` verified | estimate | incomplete), number of shops, best shop and trust label. Give `query` (free text, every word must match; 8 to 14 digits are an EAN, matched exactly) and/or `category` (a slug from GET /api/v1/deals/categories, e.g. letni-pneumatiky, mobilni-telefony), or neither to browse the whole catalogue (the website's /produkty page), or `slugs` (product slugs) to compare named products side by side; then any filters: price_min/price_max, brand, shops, shop_country (e.g. DE for offers from Germany), in_stock, on_sale, free_shipping, min_shop_rating, min_product_rating, attr (key:value pairs); sort price (lowest product price first, the default), price_desc, total (lowest total with shipping, opt-in; or include_shipping=true), total_desc, discount, shops, popular, rating, score, name. Answers at most `limit` products (default 20) from `offset`; `total_matches` counts every match, and `facets: true` adds the brands, shops, price range and attribute values with counts over the whole filtered list. Next: find_best_price with a product name for the full card with every offer, or price_history with `slug`.