Documentation

Most setups take under 2 minutes. Choose the method that fits your platform:

Need real-time notifications? Webhooks are available after tracking is live (Business & Enterprise).

A dedicated HumanKey WordPress plugin is coming soon to the official WordPress.org directory. Until then, you can add HumanKey to any WordPress site in about a minute with the 1-line JS snippet below — no plugin required.

1. 1Copy your Site Public Key from your Dashboard → Sites
2. 2Copy the HumanKey snippet from the 1-Line JS Install section below
3. 3Paste it into your site header — using your theme's header settings or a headers & footers helper plugin
4. 4Save — the tracking snippet is now live on all pages

Works on any platform that allows custom HTML: Shopify, Webflow, Squarespace, static sites, and custom apps.

Replace YOUR_PUBLIC_KEY with your site's public key from the Dashboard → Sites page.

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://api.humankey.io/api/detect.js?key=YOUR_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

// App.tsx or index.tsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.humankey.io/api/detect.js?key=YOUR_KEY';
    script.async = true;
    document.head.appendChild(script);
    return () => { document.head.removeChild(script); };
  }, []);

  return <div>{/* Your app */}</div>;
}

<script>
  (function() {
    var s = document.createElement('script');
    s.src = 'https://api.humankey.io/api/detect.js?key=YOUR_KEY';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>
<!-- Trigger: All Pages -->

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://api.humankey.io/api/detect.js?key=YOUR_KEY',
          async: true,
        },
      ],
    },
  },
});

A read-only Reporting API — aggregated reports for your site as JSON — is coming soon for Business and higher plans.

Today, the fastest way to add HumanKey to any platform is the one-line JavaScript snippet shown above: it runs on any site that allows a script tag and needs no server-side code.

Configure per-crawler rules in your Dashboard → Sites → AI Crawler Rules.

HumanKey also generates a custom robots.txt snippet based on your rules, including a machine-readable Content Signals declaration in which you choose how AI may use your content (by default: yes to search and AI answers, no to AI training — an advisory declaration of your terms, not technical enforcement). Copy and paste it into your site manually.

AI crawler check (Dashboard → AI Magnet → Overview) — shows what your homepage gives AI crawlers in its raw HTML, as crawlers that do not run JavaScript receive it — structured data, metadata, content — and what to fix first. Two separate parts, never added together: what your homepage shows (up to 30 points, measured for a site whose ownership you have confirmed and whose robots.txt allows the check) and your settings in HumanKey (up to 70 points). The headline is on every plan; the breakdown with fix links is Pro+.

The weights: JSON-LD 12, canonical 3, meta description 5, headings 4, image alt 3, length 3/2 (over 300 words 3, over 100 words 2); settings 25 / 25 / 20 (crawler rules for the main AI crawlers 25, at least one crawler rule 25, number of crawler rules 20). The weights are HumanKey's own choice, not a search-engine rule.

The score is advisory guidance based on what HumanKey can read from your page — not a ranking or visibility guarantee. Improving it does not promise AI citations or search placement.

What each check reads, why it matters, and its source. Automated checks of your public pages against the criteria listed (as of 2026-10-21); suggestions only — search engines and AI systems decide for themselves what they show and use.

• Page title present

  Search engines use the page title as one source for the title shown in their results.

  Without a title, search engines write the heading of your result themselves.

  Passes when the title tag in the page head has text.

  Per published documentationSource: Google Search Central (2026-10-21)

• Meta description present

  A short summary of the page in the page's code. Search engines sometimes show it under the title in results.

  Without a description, the text under your result is taken from anywhere on the page.

  Passes when a meta description tag has text; og:description alone is shown but does not pass.

  Per published documentationSource: Google Search Central (2026-10-21)

• Page not marked noindex

  noindex asks search engines not to show this page in their results.

  noindex asks search engines to leave this page out of their results.

  Reads the robots, googlebot and applebot meta tags, and X-Robots-Tag headers for all crawlers, Googlebot or Applebot. noindex or none in any of them fails.

  Per published documentationSource: Google Search Central, Apple Support (2026-10-21)

• No snippet limit on the page

  nosnippet and max-snippet limit how much text Google shows from the page in results and how much it uses as direct input for AI Overviews and AI Mode. Apple does not use text marked nosnippet as context for AI answers in its products.

  Snippet limits cap the page text Google and Apple show, or use for AI answers.

  A snippet limit caps how much page text Google shows or feeds its AI answers.

  Apple writes no description or answer from this page, nor uses its text in AI answers.

  Same tags and headers as noindex; nosnippet or max-snippet:0 and above fails, max-snippet:-1 passes. For Applebot only nosnippet counts; the strictest limit wins.

  Per published documentationSource: Google Search Central, Apple Support (2026-10-21)

• … sections marked data-nosnippet

  Google does not use text marked data-nosnippet as a snippet in its results.

  Google leaves the marked text out of the snippets in its results.

  Counts parts of the HTML marked data-nosnippet (span, div or section, as Google supports); information only, never marked as a problem.

  Per published documentationSource: Google Search Central (2026-10-21)

• Text readable without scripts: about …

  Some crawlers read the page without running scripts. Text that appears only after scripts run may not reach them.

  Crawlers that skip scripts get an almost empty page; the text never reaches them.

  Fails when fewer than 50 words are readable without JavaScript (our own threshold); noscript text counts.

  HumanKey's own assessment

• Site name found: …

  Google takes a site's name mainly from WebSite structured data, and also from og:site_name, the page title and other homepage text.

  Without a clear name, Google picks one from your page or from other sites.

  Read from the WebSite structured data name, then og:site_name, then the first part of the page title.

  Per published documentationSource: Google Search Central (2026-10-21)

• Structured data found: …

  Structured data is a machine-readable block (schema.org, usually JSON-LD) that names what the page is about.

  Structured data states what the page is in a form machines read without guessing.

  Passes when a JSON-LD block HumanKey can read names a schema.org type; left out when microdata or RDFa is used.

  Per published documentationSource: Google Search Central (2026-10-21)

• Canonical link present

  A canonical link names the preferred address of a page whose content is reachable under several addresses. Google treats it as a strong signal when it chooses the main address.

  Without a canonical link, Google picks the main address among duplicates from other signals.

  Passes when the HTML has a canonical link with a value; Link headers and the address are not checked.

  Per published documentationSource: Google Search Central (2026-10-21)

• Homepage opens at … without redirects

  A redirect sends crawlers from one address to another. Google treats redirects as a strong signal of the main address.

  Crawlers apply the robots.txt of … to this page, not the file of ….

  Rules in the robots.txt of … do not apply to the page at ….

  Shows where the homepage address ends after redirects; a different host name, such as with or without www, is information only.

  Per published documentationSource: Google Search Central, RFC 9309 (2026-10-21)

• Homepage is larger than HumanKey reads

  The other rows use only the part HumanKey read. Text and structured data further down were not checked.

  Shown only when the page is cut off at HumanKey's read limit; information only, never marked as a problem.

  For your information

• robots.txt found at …

  Without the file, crawlers that follow the standard may read every page.

  HumanKey could not read the file (an error, no answer, too many redirects or an unreachable address). Crawlers that cannot read it either may treat the whole site as closed.

  Without the file, crawlers that follow the standard treat every page as open.

  When the file cannot be read, crawlers following the standard may treat the site as closed.

  A 2xx answer means found, 4xx (except 429) means not found, anything else unreadable.

  Per published documentationSource: RFC 9309 (2026-10-21)

• robots.txt size: …

  Google reads the first 500 KiB of the file and ignores the rest.

  Rules after the first 500 KiB are ignored, so some of your rules never apply.

  Reads up to 500 KiB and only complete lines; a larger file fails, since Google ignores the rest.

  Per published documentationSource: Google Search Central, RFC 9309 (2026-10-21)

• Sitemap line in robots.txt

  A Sitemap line tells search engines where your list of pages is. It is one of several ways to share it; the package does not add it, because the address depends on your platform.

  A Sitemap line tells crawlers where your page list is without a separate submission.

  Passes when the file has a Sitemap: line with any value; the address is not opened or checked.

  Per published documentationSource: Google Search Central (2026-10-21)

• robots.txt lets search engines read the homepage

  Your robots.txt tells search crawlers such as Googlebot and Bingbot whether they may read the page. The package never blocks Googlebot or Bingbot and does not unblock any crawler; change these lines by hand.

  A blocked search crawler cannot read the homepage, so it has nothing to show.

  Tests whether Googlebot and Bingbot may read the homepage (/) under your rules; fails if either is blocked.

  Per published documentationSource: RFC 9309 (2026-10-21)

• Googlebot cannot read the noindex: robots.txt blocks the homepage for it

  Google cannot read rules on a page blocked by robots.txt, so it ignores the noindex. For noindex to work, Googlebot must be allowed to read the page.

  Your noindex has no effect in Google while robots.txt blocks Googlebot.

  Fails when robots.txt blocks Googlebot from the homepage (/) and a tag or header for Google says noindex.

  Per published documentationSource: Google Search Central (2026-10-21)

• Content-Signal declared: …

  A robots.txt line that states how AI systems may use your content. It states your wishes; it blocks nothing.

  The line records your wishes for AI use; a crawler may read it or ignore it.

  Shows the value of the first Content-Signal line; information only, never marked as a problem.

  For your informationSource: Cloudflare Content Signals (2026-10-21)

HumanKey can generate schema.org markup (JSON-LD) — a machine-readable description of a page that helps AI systems and search engines parse what your content is about. Generate it in Dashboard → AI Magnet → robots.txt and llms.txt (Pro plan and above).

Structured data is advisory context, not a ranking or visibility lever. It does not guarantee AI citations or search placement, and Google retired FAQ rich results in 2026 — so treat it as machine-readable context, not a rich-result badge.

Get real-time notifications when bots are detected. Available on Business and Enterprise plans.

If your account's plan no longer includes webhooks, deliveries stop once any grace period after the plan change has ended. Your endpoints stay saved, and deliveries start again after a move to a plan that includes webhooks; events from the time in between are not sent later.

POST https://your-endpoint.com/webhook
X-HumanKey-Signature: sha256=...

{
  "event": "bot.detected",
  "data": {
    "domain": "yoursite.com",
    "url": "/article/ai-trends-2026",
    "action": "block"
  }
}
// Full payload reference in Dashboard → Integrations.

Signatures use HMAC-SHA256. Verify with your webhook signing secret from Dashboard → Integrations.

HumanKey sends email notifications about your site's bot traffic. Configure each type independently in Dashboard → Settings → Email Notifications.

All notifications are enabled by default. Weekly AI insights are generated from aggregated counts for your site (totals, percentages, crawler names). Insights are advisory only (EU AI Act compliant).

HumanKey uses a privacy-preserving multi-signal classification pipeline. Every visit is evaluated against three category groups before a confidence-graded verdict is issued.

Classification runs on our servers in the EU. It uses technical data about the request and the browser — on Pro and higher plans also interaction patterns — not names, e-mail addresses or cookies. Results are available in your Dashboard.

Confidence scoring is included on all plans. Detailed analytics data is available on Pro and above.

HumanKey identifies coordinated bot networks via privacy-preserving traffic analysis. Detected groups appear in the dashboard with confidence-graded danger ratings and network operator context (sourced via public registries).

Detected bot networks appear in your dashboard's Behavior section.

Bot farm detection is informational only — no automated blocking. This analysis runs on our servers in the EU.

HumanKey offers two embeddable badges. They are different products — pick the one that matches your plan and goal.

1. Human Traffic Status Badge (all plans, including Free)

A live status widget — a small floating pill that reflects your site's last-24h human-vs-bot traffic. Add this one-line script (it carries your public key); it appears automatically, with no configuration.

<script src="https://api.humankey.io/api/widget.js?pk=YOUR_PUBLIC_KEY" async></script>

Get it in Dashboard → AI Magnet → Badges (copy the snippet). Available on every plan, including Free.

2. Embeddable Verified Badge (Pro plan and above)

A static SVG trust mark showing your verified domain, with a public click-through verification page. Enable and theme it in Dashboard → AI Magnet → Badges, then embed:

<img
  src="https://api.humankey.io/api/badge?siteKey=YOUR_PUBLIC_KEY"
  alt="HumanKey AI Verified"
  width="180"
  height="20"
/>

The badge is an SVG image served with a cache of up to 1 hour. No JavaScript required. While the Free plan is in force, a badge that was switched on earlier carries no domain; for a site whose badge is not switched on, no badge image is served.

HumanKey includes a built-in AI Assistant available on every page — both the public website and the dashboard. Click the chat icon in the bottom-right corner to start a conversation.

What you can ask:

• •Product features, pricing tiers, and plan comparisons
• •GDPR compliance, data retention, and privacy policies
• •Integration guides (WordPress plugin, JS snippet, webhooks)
• •Dashboard features, report interpretation, webhook setup
• •Billing, plan changes, and invoice management

Limitations:

• •20 messages per conversation (start a new one after)
• •Conversations are ephemeral — not saved to our database and not recoverable
• •Cannot make binding decisions. It does not read your analytics or visitor records; for signed-in users it receives only coarse account context: your plan and, where one applies, the plan that follows it and the end date of a grace period or trial, whether a subscription is recorded, the number of sites, feature usage and a traffic-volume band; when you work in another account's workspace it receives only the fact that you are a team member there
• •For complex issues, use the "Talk to a human" link → /contact

Installed the snippet but not seeing data? Here are the most common causes and fixes.

Content-Security-Policy:
  script-src 'self' https://api.humankey.io;
  connect-src 'self' https://api.humankey.io;

<script data-cfasync="false" src="https://api.humankey.io/api/detect.js?key=YOUR_PUBLIC_KEY" async></script>