Anti-Phishing HTTP API
Fetch the phishing tracking pixel via the BotBye HTTP API directly — no SDK required. This approach works with any language or platform that can make an outbound HTTP request.
Phishing is identified by a public, browser-safe clientKey carried in the URL path, so no server key is required.
Expose two routes on your own origin: an SVG route — the URL your client code passes to getCatcher({ url }) — and a PNG route that the SVG references through image_id. Each receives the browser's Origin and Referer headers and forwards the request to BotBye's /server route, building the upstream query itself and forwarding each header only when the browser sent it, then relays the response bytes back to the browser.
The paths are arbitrary, so name them like ordinary static assets — /your-image-route.svg and /your-image-route.png below — and let the route decide the format it sends upstream. A path that spells out the vendor or the feature (/api/phishing/…) is what a copied page is searched for and stripped of, and a format query param on the pixel URL reads the same way.
Proxy the tracking pixel
1
GET https://verify.botbye.com/api/v1/phishing/image/{clientKey}/server?format={png|svg}
Request headers:
| Header | Required | Description |
|---|---|---|
| Origin | no | The browser's Origin header, passed straight through when present — an <object data="…svg"> pixel sends none; omit it rather than substituting a placeholder |
| Referer | no | The browser's Referer header, passed straight through when present — omit it when the browser sent none, never substitute a placeholder |
| Module-Name | no | Your module / platform name, for attribution |
| Module-Version | no | Your module / platform version, for attribution |
Query params:
| Param | Required | Description |
|---|---|---|
| format | yes | png or svg — which image to serve. Set it from the route that was hit, not from the browser's query |
| image_id | svg only | The absolute URL of your PNG route — the returned SVG embeds it as its tracking pixel |
| executable | svg only | false — the script-less SVG — or true for the script-driven one. Send it explicitly on every call |
Build that query yourself instead of copying the browser's: image_id is what the served SVG points its pixel at, so a value taken from the incoming request lets the caller choose that URL, and executable decides whether the document you hand the browser carries JS. Attribution travels in the Module-Name / Module-Version headers on this route, not in the query. The response carries the image bytes; relay its Content-Type (image/png or image/svg+xml, per the format you sent) and body back to the browser as-is.
Omitting executable serves the script-less SVG today, which is the variant you want — but that is a server-side default, and every BotBye SDK sends the param on every call rather than riding on it. Pass executable=true only for browsers predating crossorigin on svg <image> (Chrome 118, Firefox 114, Safari 17.2), where the script-driven variant is the one that still reports.
1
2
3
4
5
6
7
8
9
10
11
12
# /your-image-route.png — forward the browser's Origin and Referer, set format from the route
curl -X GET 'https://verify.botbye.com/api/v1/phishing/image/00000000-0000-0000-0000-000000000000/server?format=png' \
--header 'Origin: https://your-site.example' \
--header 'Referer: https://your-site.example/login' \
--header 'Module-Name: HTTP' \
--header 'Module-Version: 1.0.0'
# /your-image-route.svg — image_id is your own PNG route, built from your host
curl -X GET 'https://verify.botbye.com/api/v1/phishing/image/00000000-0000-0000-0000-000000000000/server?format=svg&image_id=https%3A%2F%2Fyour-site.example%2Fyour-image-route.png&executable=false' \
--header 'Referer: https://your-site.example/login' \
--header 'Module-Name: HTTP' \
--header 'Module-Version: 1.0.0'
Report the server-side integration (recommended)
Once, at startup, send a best-effort init handshake so the Get Started flow marks the server-side integration as complete. Ignore failures — it must never block startup.
1
2
3
curl -X POST 'https://verify.botbye.com/api/v1/phishing/init-request/v1/00000000-0000-0000-0000-000000000000' \
--header 'Module-Name: HTTP' \
--header 'Module-Version: 1.0.0'