Fordeal

The 63 tools it listed

"Read only" and "Changes data" are the server's own marks. Underlined parameters are required.

1. add_to_list

   Add a product or a digital plan to a named list

   Adds a product (`product_slug`) or a digital service plan (`digital_id`, a plan id of compare_digital / compare_mobile, e.g. claude-pro) to one of the signed-in person's lists with an optional private note; send exactly one of the two. For a product its total for `deliver_to_country` today is kept as saved_total (for "the price changed since you saved it"); a plan keeps no saved price. Adding it again only changes the note. At most 200 items per list. Another person's list answers not_found.

   list_id product_slug digital_id note deliver_to_country locale

2. api_price_breakdownRead only

   Cost split of AI API models

   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.

   provider models messages_per_month input_tokens output_tokens cache_share cache_write_share batch deliver_to_country currency locale

3. cancel_energy_watchChanges data

   Cancel a fixation-end watch (deletes it)

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

   token

4. cheaper_abroadRead only

   Products cheaper from a shop in another country

   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.

   deliver_to_country locale limit

5. check_shop_feedRead only

   Check a shop's product feed and preview its offers

   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 Heur

   feed_url feed_content feed_base64 filename country domain format preview_items

6. compare_digitalRead only

   Compare digital services by price per month

   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), passw

   category usage messages_per_month input_tokens output_tokens cache_share batch images_per_month video_seconds_per_month purpose tier deliver_to_country currency locale

7. compare_energyRead only

   Household electricity and gas by yearly cost

   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. El

   country commodity distributor rate mwh nt_mwh breaker postcode current_monthly current_offer current_vt_price current_nt_price current_fee_month current_prices_vat fixation pricing green no_penalty sort compare locale household limit

8. compare_energy_from_billRead only

   Household electricity or gas from the values on a bill

   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.

   commodity distributor rate breaker vt_mwh nt_mwh period_days vt_price_mwh nt_price_mwh fee_month monthly_advance locale limit

9. compare_internetRead only

   Compare home internet providers

   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.

   country technology min_speed_mbps min_price max_price commitment_months provider sort limit offset

10. compare_mobileRead only

    Mobile tariffs by what you need

    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.

    country operator data_gb unlimited_calls commitment_months esim five_g sort minutes sms no_commitment roaming_eu_gb limit

11. confirm_energy_watch

    Confirm a fixation-end watch (the person's click)

    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.

    token

12. create_list

    Create a named list

    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.

    name locale

13. daily_dealsRead only

    Biggest price drops of the last 24 hours

    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.

    country category min_percent stated_only limit max_per_shop locale

14. delete_comparisonChanges data

    Delete a saved comparison

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

    comparison_id

15. delete_listChanges data

    Delete a named list

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

    list_id

16. delete_my_accountChanges data

    Delete the person's account for good (typed confirmation)

    Deletes the signed-in person's account and cannot be undone. Ask the person first and pass `confirm` = the account's e-mail exactly as they type it; without it nothing happens (validation, confirmation_required). In order: every session is revoked; every row of the account is deleted or anonymised in one transaction (favourites, lists and share links, comparisons, price watches including watches set without an account from the same e-mail, energy watches, reviews, devices, every queued or sent mail; error reports, page notices and the audit trail keep their text without the person); the sign-in itself is deleted; one last notice goes to the address. Answers deleted, scope, counts per table, notice and `what` (deleted / anonymised / kept). The token stops working.

    confirm locale

17. delete_price_watchChanges data

    Cancel a price watch

    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.

    watch_id

18. digital_price_historyRead only

    Recorded price changes of digital plans

    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. Also rises: the price rises of the last 45 days (from -> to in one currency, period month | year, detected_on, source_url; status proposed = the official page shows the higher price and our list waits for confirmation, confirmed = our price list holds it; a yearly price is compared per month, two currencies never), and watch_coverage: how many priced plans a robot reads daily or weekly and which wait on the manual weekly list. Filter by plan (the id from /digital/plans).

    plan limit

19. energy_price_historyRead only

    Household electricity and gas prices over time

    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.

    country commodity

20. energy_suppliersRead only

    Household energy suppliers with their products and where to find the bill

    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.

    country id locale

21. energy_unit_pricesRead only

    Price of one kWh of electricity and gas

    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.

    country rate mwh gas_mwh locale

22. energy_watch_statusRead only

    State of a fixation-end watch from its e-mail link

    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.

    token

23. estimate_appliance_energyRead only

    Yearly consumption and cost of a fridge, a washing machine or heating

    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.

    kind label_kwh_year kwh_per_100_cycles washes_per_week area_m2 heat_need_kwh_m2 source scop efficiency distributor price_per_kwh country locale

24. find_best_priceRead only

    Find the best price for a product

    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, rating_url = the public page of the source that rating comes from or null, total

    query deliver_to_country verified_only sort include_shipping budget deep locale

25. get_my_profileRead only

    The signed-in person's profile and settings

    The profile of the person whose Supabase access token is sent (an agent API key is refused): id, email, name (shown with reviews), locale (language of our e-mails), country (market: the delivery country they compare for), watch_emails (false = every price-watch e-mail paused; security notices are always sent), how many price watches are active and paused, created_at, last_sign_in_at and `markets` to choose from. `deletion` says in words what delete_my_account removes, anonymises and keeps. Next: update_my_profile, sign_out, delete_my_account.

26. get_productRead only

    Today's card for a known product id

    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.

    product deliver_to_country verified_only sort include_shipping ai locale

27. get_shop_feed_diagnosticsRead only

    Feed diagnostics of a compared shop

    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.

    slug

28. get_shop_registrationRead only

    Status of a shop registration

    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.

    id

29. get_shop_statisticsRead only

    Clicks Fordeal sent to a shop

    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.

    shop from to

30. insurance_guideRead only

    Insurance: insurers' facts, public ratings and official websites (no prices, no ranking)

    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 a

    country kind online assistance app claim_online sort compare locale

31. list_couponsRead only

    Shop coupons and promotions valid today

    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 lis

    country limit

32. list_my_comparisonsRead only

    The signed-in person's saved comparisons

    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`.

    locale

33. list_my_favoritesRead only

    The signed-in person's favourites

    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.

34. list_my_listsRead only

    The signed-in person's named lists

    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 items (newest first): products (kind product, the private note and the total saved at that time) and digital plans (kind digital, `digital_id` = plan id of compare_digital / compare_mobile, note only), 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=.

    locale

35. list_my_price_watchesRead only

    The signed-in person's price watches with today's price

    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.

    locale

36. list_my_shopsRead only

    Shops the signed-in person looks after

    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.

37. list_shopsRead only

    Which shops are compared, with ratings

    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".

    country

38. manage_price_watchChanges data

    Confirm, pause, resume, retarget or cancel a price watch from its mail link

    The buttons of /{locale}/hlidac, one action on the one watch the signed token names, no sign-in: `confirm` (only the confirmation token of watch_product_price: the person's double opt-in click, an agent passes it only on the person's word), `pause` / `resume`, `set_target` with `target_total` (in the watch's currency; null = any real drop) and `cancel` (deletes the watch and its trigger history; switched off in one call, repeated calls answer status cancelled). The pause link is also the List-Unsubscribe one-click address of every alert. Answers the watch as price_watch_status shows it.

    t action target_total locale

39. most_searched_productsRead only

    The most searched product queries of a country (daily ranking)

    The 30 most searched product queries of one delivery country, recomputed once a day by the worker from three free sources: Google Trends' public daily-trends RSS of the country (about ten queries of the last day with an approximate traffic; it has no public shopping filter, so a trend stays only when it matches our products), forDeal's own search log of the country and the human clicks to a shop of the last 7 days. Each entry is `query` (the most frequent spelling), `rank`, `score` = 15 × log2(1 + trends traffic / 100) + 25 × log2(1 + searches) + 20 × log2(1 + clicks), `parts`, `raw` (traffic, searches, clicks, matched products), `sources` and `product`: the product that stands for the query, a summary like search_products (only products with a photo and offers from two or more shops; one product once). `group` is the home rows' group name, `date` the day of the ranking; `generated_at` null before the first run. Next: get_product with the product slug for the full comparison.

    country deliver_to_country locale limit

40. price_historyRead only

    Price history of a product

    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; is_lowest wins: the lowest price of the period is never recently_cheaper; recently_cheaper = more than 8 % above the 30-day low); `advice` (lowest | low | recently_cheaper | usual | high | short | sparse | stale) is the one key derived from it, and find_best_price carries the same object, the same advice and a verdict that never contradicts it (wait only with recently_cheaper, or in the sale season above a lower price of the

    product days currency deliver_to_country locale

41. price_watch_statusRead only

    One price watch by the signed link of its mail

    What the link in a price-watch mail opens (/{locale}/hlidac?t=…), without an account: the product, status (pending | active | paused | cancelled), target_total and saved_total in the watch's currency, the delivery country, last_alert_at and `last_trigger` (when the watch last fired: total, target, shop and the captured_at of that price; null before the first), and `purpose` manage | confirm (the confirmation link of watch_product_price). No e-mail address, no other watch. Next: manage_price_watch with the same token.

    t locale

42. product_rowsRead only

    Today's product rows: deals of the day, trending, seasonal gift tips

    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

    deliver_to_country locale date

43. product_variantsRead only

    Other capacities, colours and sizes of a product

    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.

    product deliver_to_country locale

44. register_shop

    Register a shop for the comparison

    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 operat

    shop_name domain country email feed_url feed_content feed_base64 feed_filename affiliate terms_version accept_terms locale note website

45. remove_favoriteChanges data

    Remove a favourite

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

    kind id

46. remove_from_listChanges data

    Remove a product or a digital plan from a named list

    Removes a product (`product_slug`) or a digital plan (`digital_id`) from one of the signed-in person's lists; send exactly one of the two. `removed: false` when it was not there. Another person's list answers not_found.

    list_id product_slug digital_id locale

47. report_illegal_content

    Report illegal content (DSA Art. 16)

    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.

    content_kind page_url product_slug explanation name email good_faith locale ip_hash website

48. report_issue

    Report a wrong price, variant or shop

    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.

    kind product_slug message offer_id shop_slug email locale page_url user_agent_hash ip_hash website

49. save_comparison

    Save a comparison of digital plans

    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.

    items name locale

50. save_favorite

    Save a product or a digital plan to favourites

    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. For a product its total for `deliver_to_country` today is kept as saved_total (for "the price changed since you saved it", as the website's heart does); a plan keeps no saved price. Saving twice changes nothing (the first saved price stays). Adding it to a named list (add_to_list) or deleting that list leaves the favourite as it is.

    kind id deliver_to_country

51. search_productsRead only

    Search and filter compared products

    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_s

    query q category slugs deliver_to_country locale limit offset facets facet_attributes price_min price_max brand shops shop_country in_stock on_sale free_shipping min_shop_rating min_product_rating attr sort include_shipping

52. send_contact_message

    Write a message to Fordeal (the contact form)

    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 [email protected] 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.

    name email topic message locale ip_hash nickname

53. send_cooperation_inquiry

    Write to Fordeal about cooperation (partners, media, creators)

    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.

    kind name email message organization website markets cooperation_type topic deadline links locale ip_hash nickname

54. set_price_watchChanges data

    Watch the total price of a product

    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.

    product_slug target_total deliver_to_country locale

55. share_comparisonChanges data

    Share or stop sharing a saved comparison

    `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.

    comparison_id shared locale

56. sign_outChanges data

    Sign the person out (revoke the sessions)

    Signs the person out: scope global (default) revokes every session of the account on every device, local only the session of this token. The access token is refused from then on; the person needs a new e-mail sign-in link. Saved favourites, lists and watches stay.

    scope

57. trending_new_productsRead only

    The most searched new products today (the home page's first row)

    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 sh

    deliver_to_country locale limit

58. update_listChanges data

    Rename, share or stop sharing a named list

    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.

    list_id name shared locale

59. update_my_profile

    Change the signed-in person's profile and settings

    Changes only the fields sent: name (at most 40 characters, empty string clears it), locale (language tag of our e-mails, e.g. cs), country (one of the markets of get_my_profile, null clears it), watch_emails (false pauses every active price watch of the account and remembers which; true resumes exactly those, never a watch the person paused themselves). Needs the person's access token. Answers the profile with `changed` (and watches_paused / watches_resumed).

    name locale country watch_emails

60. update_price_watchChanges data

    Pause, resume or change the target of a price watch

    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.

    watch_id paused target_total locale

61. verify_shop_domain

    Prove a shop's domain with a meta tag or a file

    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.

    domain token

62. watch_energy_fixation

    Watch the end of a fixed energy price (e-mail before it ends)

    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.

    email fixation_end commodity distributor rate mwh nt_mwh supplier_id current_offer_id country locale ip_hash website

63. watch_product_price

    Watch the total price of a product without an account (e-mail, double opt-in)

    No account (UX-72): the person gives an e-mail and Fordeal mails them when the recommended total for `deliver_to_country` (goods + shipping, the product page's meaning) falls under `target_total` (default: today's total, i.e. any real drop by the currency's step), never twice for one price and at most once a day. Double opt-in: the address first gets only a confirmation link; nothing else is sent before the person clicks it (an agent cannot confirm for the person). Every alert has pause and cancel links that work without signing in (GET/POST /api/v1/price-watches/link). Unconfirmed watches are deleted after 7 days, confirmed ones 365 days after the confirmation. One watch per address and product, at most 20 per address; the answer is the same whether the address is known or not. Ask the person for consent before passing their e-mail. A signed-in person can use set_price_watch instead (no confirmation needed).

    email product_slug target_total deliver_to_country locale ip_hash website