← All guides · Published November 14, 2026 · Reviewed November 14, 2026 · By the Ingenious AI team · 6 min read
How Does the Classify API Identify an AI Agent from a User-Agent?
The short answer: you send it a user-agent string and it returns the database's verdict: BLOCK with the matched agent's ID, ALLOW with the ID for the utility class, or UNKNOWN. The classifier matches only vendor-verified substrings — reported tokens like GrokBot and watch entries classify UNKNOWN by design, a property the codebase's own self-test asserts. It is part of the Team tier (the classify/database API), for owners who need agent identification inside their own systems rather than only at their website's edge.
Build my block kit — free · Test a policy in the simulator first
What is the classify API?
AgentBlock's Team-tier endpoint that classifies a user-agent string against the agent database, returning BLOCK:
Three answers, and the third is the point
Most identification APIs pretend the world is fully labelled: every input gets a confident name, and the confidence is the product. The classify API's distinguishing feature is its third answer. UNKNOWN is returned for stock browser strings, for empty strings, for reported tokens and for watch agents — a tested refusal to guess that mirrors the database's evidence grades. A consumer of this API can build on the verdicts precisely because the API declines to invent the ones it cannot support.
The two positive verdicts are equally disciplined. BLOCK:
Where programmatic classification earns its keep
Inside your own plumbing: a log pipeline enriching events with agent identities before they reach analytics; a WAF or gateway rule that wants a verdict from the graded database rather than a regex list copied from a blog post; a data platform labelling historical traffic to answer 'when did retrieval agents first arrive?' retroactively; an agency's reporting job classifying across client logs uniformly, so every site's evidence speaks the same vocabulary.
The common thread is vocabulary. Once classification is an API, every system in an organisation calls the same agent by the same ID with the same grade — and cross-system arguments about what visited whom mostly evaporate.
The database API beside it
Team's API pairing exposes the database itself alongside the classifier: the entries, classes, evidence grades and version — the reference data the classifier's verdicts cite. Consumers can therefore build interfaces that explain a verdict ('BLOCK:claudebot — training class, verified, source: Anthropic documentation') rather than merely relaying it, and can watch the version field to know when the world their integration describes has moved.
Version visibility closes the integration loop the same way the stale check closes the kit loop: an API consumer whose cached picture is two versions old should find out from the data, not from a confused client.
Keys, scope and honest limits
The API is a Team entitlement, accessed with the account's API keys — the owner tooling mints and manages them, and a key's compromise is handled by revocation and rotation rather than by hoping. Rate behaviour and plan limits apply as documented on the pricing page; the API is a classification service, not a data firehose.
And its limits are the database's limits, unchanged by being an API: spoofed claims classify by their claimed name (sender verification is an edge function, not a string function), watch agents return UNKNOWN, and no verdict about a string is a verdict about the intentions of whoever sent it. The API grades names. Judgement remains, properly, with the systems and people consuming it.
Five actions to take today
- Build for UNKNOWN. Any consumer of the classify API must treat UNKNOWN as a first-class outcome — it is the verdict that keeps the other two trustworthy.
- Store the agent ID, not just the verdict. IDs are the stable vocabulary across systems; verdicts without identities cannot be re-graded when the database moves.
- Watch the database version. Integrations should surface the version they classified against, exactly as kits and evidence packs do.
- Guard the keys like credentials. Mint per-system keys from the owner tooling, revoke on suspicion, rotate on staff changes.
- Keep sender checks at the edge. The API classifies strings; SPOOF-SUSPECT judgements need request context only your edge has.
Worked example: a data platform labels two years of traffic
Switchyard Reviews, the fictional comparison site, wanted to know when AI-answer referrals had really begun — its analytics platform only labelled referrers, not the crawlers behind them. Its data engineer ran two years of stored access logs through classification: 1.9 million requests resolved to named agents with IDs and classes; 71% of the remainder resolved to ordinary browser patterns, and the UNKNOWN residue was reported as itself rather than forced into names.
The labelled history rewrote the company's strategy timeline. Retrieval agents had been fetching its comparison pages for eleven months before the first visible referral spike — the citation pipeline had been filling long before it showed — and training volume had tripled in a single quarter the year before, unnoticed.
Both findings changed live decisions: retrieval allowances were confirmed with retroactive evidence, and the training block's value could finally be stated in the site's own historical numbers instead of in principle.
Frequently asked questions
What does the classify API return for GrokBot?
UNKNOWN. GrokBot is a reported entry — directory-listed, not vendor-published — and only verified entries can match. The codebase's self-test asserts exactly this: a bare GrokBot string classifies UNKNOWN, as do stock browser strings and the watch agents' names.
How is the classify API accessed?
Through the Team tier's API entitlement, using API keys managed in the owner key tooling. Team ($79/mo) bundles it with the database API, the AgentGate export, bulk verification and the pack tool — the programmatic tier of the platform.
Can the API tell me if a request is spoofed?
No — it classifies the string it is given. Sender verification compares the request's origin against vendor IP ranges and happens at the edge, inside the Worker, where the request context exists. Use each where its evidence lives.
What user-agents return ALLOW?
Matches in the utility class — in the current database, facebookexternalhit, the link-preview fetcher. ALLOW:<id> tells a consumer the string is a known agent whose class default is welcome, distinct from an unmatched string, which is UNKNOWN.
How do I keep an integration current?
Read the database version the API reports and track it like a dependency version. When it moves, your cached assumptions about classes and grades are stale in exactly the way the stale check describes for kits — refresh them deliberately.
Related guides
- How to Block AI Scrapers and Bots from Your Website
- Which AI Crawlers Should You Allow?
- How Do You Block AI Bots on WordPress, Cloudflare, or Plain JS?
- Pre-deploy breakage simulator — test a policy before it ships
- Impact preview — your server log against a draft policy
- Why Can Meta-ExternalFetcher Bypass Your Robots.txt?
- Why Should You Never Block facebookexternalhit?
- What Is FirecrawlAgent and Should Your Site Block It?
- How Do Rate Limits Work for AI Crawlers?
- How Do Path Rules Protect Checkout, Login and Admin Pages from AI Agents?
- Block evidence — parse a log, build an evidence pack
- The dated agent database — 25 entries, graded