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 path | Description |
|---|---|
GET /health | service status, no cache |
GET /blocklist | confirmed risky domains: {version, count, sources[], domains:[[domain, source],…]}. ETag + If-None-Match → 304. Clients must show the attribution (sources[].attribution). |
GET /known-shops | known shops for similarity matching: {version, count, shops:[…]}, ETag as above |
GET /domain?name=example.com | blocklist match, known shop, domain age (age.status: found | not-registered | unknown) |
POST /reports | body {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.