For developers

API v1 is public and needs no key. Clients send only the domain name; addresses with a path, scheme or port are rejected. Responses are UTF‑8 JSON, errors { "error": "…" }.

Base: https://dvojnik.ystvan.com/api/v1

Endpoints

Method and pathDescription
GET /healthservice status, no cache
GET /blocklistconfirmed risky domains: {version, count, sources[], domains:[[domain, source],…]}. ETag + If-None-Match → 304. Clients must show the attribution (sources[].attribution).
GET /known-shopsknown shops for similarity matching: {version, count, shops:[…]}, ETag as above
GET /domain?name=example.comblocklist match, known shop, domain age (age.status: found | not-registered | unknown)
POST /reportsbody {domain, category, note?}; category: fake-shop | phishing-payment | fake-carrier | other. 201 with id; duplicate within a week → 200 with the original id; 20/day limit → 429
GET /reports/{id}report status: received | verifying | confirmed | rejected
curl "https://dvojnik.ystvan.com/api/v1/domain?name=alza.cz"

Shared core

The extension, the mobile app and the API use the same core (@dvojnik/core): domain parsing (punycode, skeleton for confusable characters), similarity search against known shops, scoring and the texts. That’s why the browser and the phone give the same result.

Extension for development and testing

The extension can be loaded unpacked: in Chrome/Edge open chrome://extensions, enable developer mode and choose “Load unpacked” with the build folder; in Firefox about:debugging → “Load Temporary Add-on”. Automated testing uses Playwright with --load-extension.

Test mode: an address ending in .localhost is evaluated as the domain before that suffix (alza-vyprodej.cz.localhost → alza-vyprodej.cz), so you can test without visiting a real risky site.

API usage rules

  • Don’t send full addresses or personal data; nothing identifying a person in the report note.
  • Respect ETag and cache (s-maxage=300 on lists) – refreshing lists every few hours is enough.
  • When showing the blocklist, credit the source (ČOI) and phrase a listing as risk signals, not proof of fraud.