// documentation

Integration guide.

Deflector works with any stack. Add one script tag and bots start getting poisoned in under 5 minutes.

Quick Start

After creating a site in your dashboard, copy your snippet tag and paste it before the closing </body> tag of every page you want to protect.

<script src="https://app.deflector.dev/api/snippet?key=YOUR_API_KEY" async></script>

That's it. Detection starts immediately. No build step, no npm package, no config.

Your API key is shown in Settings → API Keys and in the snippet copy button on the Sites page.

How it works

Deflector uses a three-stage pipeline on every page view:

Detect — The snippet sends browser fingerprint signals to /api/detect. The server checks the user-agent against 50+ known bot signatures and scores 18 fingerprint signals (WebGL, Canvas, hardware concurrency, webdriver flag, etc.).
Generate — If a bot is detected and your plan includes AI poisoning, the snippet fetches AI-generated false content from /api/poison. Claude generates contextually accurate but factually wrong HTML.
Inject — The poison HTML is appended to the DOM in a hidden container (position:absolute;left:-9999px + aria-hidden). Human visitors never see it. Scrapers that read the raw DOM get poisoned data.

A honeypot link (invisible to humans) is also injected on every page. If a bot follows it, confidence jumps to 100% and poison is guaranteed.

Installation

Plain HTML / Any site

Paste before </body>:

<script src="https://app.deflector.dev/api/snippet?key=YOUR_API_KEY" async></script>

Next.js (App Router)

Add to your root layout.tsx:

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://app.deflector.dev/api/snippet?key=YOUR_API_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}

React / Vite

Add to index.html in your public/ folder before </body>:

<script src="https://app.deflector.dev/api/snippet?key=YOUR_API_KEY" async></script>

Shopify

In your Shopify Admin, go to Online Store → Themes → Edit code. Open theme.liquid and paste before </body>.

Webflow

Go to Project Settings → Custom Code → Footer Code and paste the script tag.

WordPress

Download the pre-configured WordPress plugin from Settings. It auto-injects the snippet in your theme's footer and adds a Deflector admin page to your WordPress dashboard.

Go to Settings and click Download WordPress Plugin for your site.
In WordPress Admin: Plugins → Add New → Upload Plugin.
Upload the .php file and click Activate.
Done — protection is active immediately.

The plugin is pre-configured with your API key. No manual settings needed.

Cloudflare Worker

The Cloudflare Worker integration works at the edge — before your origin server — and injects poison directly into the HTML response. This works for static sitesthat can't run JavaScript and for maximum-performance setups.

Download the Worker script from Settings → Download CF Worker.
Go to dash.cloudflare.com → Workers & Pages → Create Worker.
Paste the entire script content and deploy.
Add a Route: yourdomain.com/* → your worker.
If proxying a static host (Netlify, S3, GitHub Pages), set ORIGIN at the top of the script to your host URL.

The Worker detects bots server-side using user-agent patterns with zero latency. It also proxies the /__deflector_hp honeypot path.

Static Sites (Build Hook)

Static site generators (Next.js static export, Astro, Hugo, Jekyll, Eleventy) produce HTML files at build time. Since there's no server to run JavaScript, the client-side snippet won't catch AI crawlers that don't execute JS — which is most of them.

The Build Hook API lets you bake poison content directly into your HTML at build time, so any crawler that fetches raw HTML gets the poison without needing JS execution.

How to use

During your build, for each page you want to protect, call the build hook endpoint with your page content. Embed the returned HTML fragment into your static HTML before </body>.

POST https://app.deflector.dev/api/build-hook

Headers:
  Content-Type: application/json
  X-API-Key: YOUR_API_KEY

Body:
{
  "pageContent": "Your real page content here...",
  "intensity": "medium",
  "domain": "yoursite.com"
}

Response:
{
  "html": "<div aria-hidden='true' style='position:absolute;left:-9999px'>...</div>",
  "cached": false
}

Next.js static export example

// scripts/inject-poison.mjs
// Run: node scripts/inject-poison.mjs

import { readFileSync, writeFileSync, readdirSync } from 'fs'
import { join } from 'path'

const API_KEY = process.env.DEFLECTOR_API_KEY
const API_URL = 'https://app.deflector.dev/api/build-hook'
const OUT_DIR = './out' // Next.js static export dir

async function injectPoison(htmlPath) {
  const html = readFileSync(htmlPath, 'utf8')
  const text = html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()

  const res = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify({ pageContent: text.slice(0, 3000), intensity: 'medium', domain: 'yoursite.com' }),
  })

  const { html: poisonHtml } = await res.json()
  if (!poisonHtml) return

  const patched = html.replace('</body>', poisonHtml + '</body>')
  writeFileSync(htmlPath, patched)
  console.log('Poisoned:', htmlPath)
}

// Find all .html files in out/
function findHtml(dir) {
  return readdirSync(dir, { withFileTypes: true }).flatMap((f) =>
    f.isDirectory() ? findHtml(join(dir, f.name)) : f.name.endsWith('.html') ? [join(dir, f.name)] : []
  )
}

for (const path of findHtml(OUT_DIR)) {
  await injectPoison(path)
}

Add node scripts/inject-poison.mjs to your build pipeline (e.g., after next build && next export) to protect every static page automatically.

API Reference

All API endpoints are available at https://app.deflector.dev/api/. CORS is enabled for all origins.

POST /api/detect

Classify an incoming request as bot or human. Call this from your snippet or server-side middleware.

// Request
{
  "apiKey": "YOUR_API_KEY",
  "url": "https://yoursite.com/page",
  "signals": {             // Optional browser fingerprint signals
    "hasWebGL": true,
    "hasCanvas": true,
    "hasTouchEvents": false,
    "pluginCount": 3,
    "hardwareConcurrency": 8,
    "webdriverPresent": false,
    // ... 12 more signals
  }
}

// Response
{
  "isBot": true,
  "confidence": 0.97,
  "method": "user_agent",  // "user_agent" | "fingerprint" | "honeypot" | "behavior"
  "botName": "GPTBot",
  "siteId": "uuid",
  "intensity": "medium",
  "aiPoisoning": true      // false on Free plan
}

POST /api/poison

Generate AI-powered poison content for a page. Content is cached for 24 hours per page+intensity combination.

// Request (use apiKey OR siteId)
{
  "apiKey": "YOUR_API_KEY",
  "pageContent": "Your real page content (up to 3000 chars)",
  "intensity": "medium",    // "subtle" | "medium" | "aggressive"
  "domain": "yoursite.com"
}

// Response
{
  "html": "<div aria-hidden='true' ...>...</div>",
  "cached": false
}

GET /api/snippet?key=YOUR_API_KEY

Returns the self-contained JavaScript snippet. Cached for 5 minutes (CDN-friendly). Add as a <script src=> tag.

POST /api/build-hook

Generate poison content at build time for static sites. Authenticated via X-API-Key header.

// Request
Headers: { "X-API-Key": "YOUR_API_KEY" }
{
  "pageContent": "...",
  "intensity": "medium",
  "domain": "yoursite.com"
}

// Response
{
  "html": "<div aria-hidden='true' ...>...</div>",
  "cached": false
}

GET /api/honeypot?k=YOUR_API_KEY

Honeypot trap endpoint. Any request here confirms the visitor is a bot. The snippet injects a hidden link to this URL on every protected page.

Poison Intensities

Configure per-site from the Sites page.

[subtle]

Subtle

95% accurate. Minor price/date/spec changes. Hard to detect. Best for sites where you want to stay stealthy.

[medium]

Medium

Clearly wrong but plausible. Wrong prices, changed names, altered statistics. Recommended default.

[aggressive]

Aggressive

Fully fabricated. Fake executives, made-up partnerships, contradictory prices. Also injects fake JSON-LD structured data.

FAQ

Does Deflector slow down my site?

No. The snippet loads asynchronously (async attribute) and only activates for bot traffic. Human visitors experience zero overhead. Detection API response time is under 5ms at edge.

Can my real visitors see the poison content?

No. Poison content is positioned off-screen using absolute CSS positioning (-9999px) and aria-hidden='true'. It's invisible to sighted users and screen readers, but sits in the DOM where bots read it.

What if Deflector incorrectly classifies a human as a bot?

False positives are extremely rare because we require multiple signals to agree before flagging someone as a bot. Even if a false positive occurs, the human visitor sees nothing different — the poison HTML is invisible.

Does AI poisoning work on the Free plan?

No. Bot detection (user-agent + fingerprinting + honeypot) is available on all plans. AI-generated poison content requires Pro or Business.

What AI model generates the poison content?

We use Claude (claude-haiku-4-5) by Anthropic. Content is generated based on your real page content and cached for 24 hours to minimize costs.

How does the Cloudflare Worker differ from the snippet?

The snippet is client-side JavaScript that runs in the browser — it needs JS execution to work. The Cloudflare Worker runs at the edge server, modifying HTML before it reaches the browser. This means it works for bots that don't execute JavaScript (most AI crawlers fetch raw HTML).

Can I use Deflector on multiple domains?

Yes. Add each domain as a separate site in your dashboard. Free plan allows 1 site, Pro allows 5, Business allows unlimited.

Is my site's real content sent to Anthropic?

The snippet sends up to 3,000 characters of your page's visible text to generate contextually appropriate poison. We don't store your content beyond the 24-hour cache TTL. See our Privacy Policy for full details.

Still need help?

Email us at support@deflector.dev

Get started free →