{"slug": "how-to-protect-your-ai-endpoints-with-vercel-botid", "title": "How to protect your AI endpoints with Vercel BotID", "summary": "Vercel launched BotID, a tool that verifies requests to AI endpoints come from real browsers before inference runs, using an invisible CAPTCHA and server-side classification to block automated clients. The tool allows developers to set detection levels per route, with Deep Analysis using machine learning to catch sophisticated bot networks in real time, as demonstrated when it traced a 500% traffic spike to a new bot network and blocked it within 10 minutes without manual intervention.", "body_md": "[Vercel BotID](https://vercel.com/botid) lets you verify that each request to your AI endpoints comes from a real browser before any inference runs. Working as an invisible CAPTCHA, it attaches a client-side challenge to requests on the routes you protect, and a server-side `checkBotId()`\n\ncall classifies each one, so automated clients are turned away before they reach your model. Running it on every request instead of once per session means an attacker can't bypass it once and reuse that access across thousands of stolen calls.\n\nThis guide walks you through installing BotID, declaring an AI route on the client, and gating that route with `checkBotId()`\n\non the server so inference runs only for verified requests. You'll also set detection levels per route, enabling Deep Analysis on your highest-value endpoints and basic checks elsewhere, and learn how to let legitimate automation through with a [Vercel WAF](https://vercel.com/security/web-application-firewall) bypass rule.\n\nBefore you begin:\n\n- A JavaScript project\n[deployed on Vercel](https://vercel.com/docs/projects/managing-projects#creating-a-project) - An AI endpoint that accepts frontend requests, such as a route built with\n[AI SDK](https://ai-sdk.dev) - A Pro or Enterprise plan to use\n[Deep Analysis](https://vercel.com/docs/botid#deep-analysis)(Basic is available on all plans)\n\nAdd BotID to your project:\n\nWrap your Next.js config with `withBotId`\n\n. This sets up proxy rewrites so that ad-blockers and third-party scripts can't weaken BotID's protection:\n\nFor Nuxt, SvelteKit, and other frameworks, the setup follows a similar pattern. See the [BotID getting started guide](https://vercel.com/docs/botid/get-started) for the per-framework versions.\n\nCall `initBotId()`\n\nduring client initialization and list the AI routes you want to protect. BotID uses this list to attach challenge headers to matching requests. If a route isn't declared here, its requests arrive without those headers, so `checkBotId()`\n\nhas nothing to verify and treats them as bots.\n\nFor Next.js 15.3 and later, use `instrumentation-client.ts`\n\n:\n\nOn earlier versions of Next.js, mount the `<BotIdClient />`\n\ncomponent in your root layout `head`\n\ninstead, passing the same `protect`\n\narray.\n\nCall `checkBotId()`\n\ninside the route handler, before the AI call runs. This is the load-bearing step: it returns a classification for the request currently being served, so a blocked request never reaches your model.\n\nPlacing the check before `runInference`\n\nmeans you incur the inference cost only for verified requests.\n\nBasic validation catches many less sophisticated bots and runs free on all plans. For high-value AI routes, enable Deep Analysis, which uses a [Kasada-powered](https://www.kasada.io/) machine learning model to analyze thousands of client-side signals.\n\nBecause Deep Analysis learns and adapts in real time, it can catch coordinated attacks that first appear as legitimate traffic. In one incident, it traced a 500% traffic spike to a new bot network by correlating identical browser fingerprints cycling across proxy nodes, then reclassified and blocked those sessions within roughly 10 minutes, without any manual intervention. For the full breakdown, see how [BotID Deep Analysis caught a sophisticated bot network in real time](https://vercel.com/blog/botid-deep-analysis-catches-a-sophisticated-bot-network-in-real-time).\n\nVisit the [Bot Management](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Ffirewall%2Fbot-management) page in your project settings, then click the Configure button to open the configuration settings and enable Deep Analysis.\n\nThis feature is available for all customers on [Pro and Enterprise plans](https://vercel.com/docs/botid#pricing). Only requests that invoke `checkBotId()`\n\nare charged, passive page views are not.\n\n- Run the check before inference: Keep\n`checkBotId()`\n\nahead of the model call in your handler, so a blocked request never costs you a token. - Set detection levels per route: Use\n`advancedOptions.checkLevel`\n\nto apply`deepAnalysis`\n\nto your most sensitive routes and`basic`\n\nelsewhere. The`checkLevel`\n\nmust be identical in your client and server configuration for each route, or verification will fail. This is available in`botid@1.4.5`\n\nand later.\n\nBlocking based on `isBot`\n\nalone also blocks legitimate automated agents, such as crawlers (e.g., Googlebot) and AI assistants (e.g., ChatGPT). To let specific agents through, use the verified-bot fields that `checkBotId()`\n\nreturns along with `isBot`\n\n.\n\nVercel identifies these agents from its [verified bot directory](https://bots.fyi/) and returns `isVerifiedBot`\n\n, `verifiedBotName`\n\n, and `verifiedBotCategory`\n\n, so you can allow an agent like ChatGPT Operator while still blocking everything else.\n\nFor a trusted service that isn't in the verified bot directory, add a [bypass rule in the Vercel WAF](https://vercel.com/docs/vercel-firewall/firewall-concepts#bypass) rather than removing protection from the route. See [Handling Verified Bots](https://vercel.com/docs/botid/verified-bots) for the full list of agents and categories.\n\nConfirm the route is declared in your client `protect`\n\narray with a matching `path`\n\nand `method`\n\n. BotID only attaches challenge headers to declared routes, so an undeclared route has nothing for the server to verify.\n\nBotID runs JavaScript in the browser session and sends headers to the server, so a direct request from curl or a browser address bar is treated as a bot in production. To test a protected route, make a `fetch`\n\nrequest from a page in your own application.\n\nLocal development returns `isBot: false`\n\nunless you set the `developmentOptions`\n\noption on `checkBotId()`\n\n. See [Local Development Behavior](https://vercel.com/docs/botid/local-development-behavior) in the BotID docs for instructions on simulating bot traffic.\n\n[BotID overview](https://vercel.com/docs/botid)[Get Started with BotID](https://vercel.com/docs/botid/get-started)[Advanced BotID Configuration](https://vercel.com/docs/botid/advanced-configuration)[Handling Verified Bots](https://vercel.com/docs/botid/verified-bots)[How Nous Research used BotID to block automated abuse at scale](https://vercel.com/blog/how-nous-research-used-botid-to-block-automated-abuse-at-scale)[BotID Deep Analysis catches a sophisticated bot network in real-time](https://vercel.com/blog/botid-deep-analysis-catches-a-sophisticated-bot-network-in-real-time)\n\nVercel BotID is an invisible CAPTCHA that confirms a request comes from a real browser before any inference runs. It attaches a client-side challenge to the routes you protect, then a server-side `checkBotId()`\n\ncall classifies each request and turns away automated clients before they reach your model. Because the check runs on every request rather than once per session, an attacker can't bypass it once and reuse that access.\n\nThere are four steps. Install the `botid`\n\npackage, wrap your framework config with `withBotId`\n\n, declare the route on the client with `initBotId()`\n\n, then call `checkBotId()`\n\nin your route handler before the model runs. Keeping the check ahead of the inference call means a blocked request never costs you a token.\n\nNo. The detection runs asynchronously inside the client session, so it doesn't block page loads or add noticeable latency for real users. The script that gathers browser signals is lightweight, and on the server `checkBotId()`\n\nonly reads the verdict that's already attached to the request, so your handler isn't waiting on a separate analysis step. Since the check runs before inference, it can lower your overall costs by stopping bot requests before they trigger an expensive model call.\n\nNo. Basic validation runs free on all plans and catches many less sophisticated bots. Deep Analysis, which uses a Kasada-powered machine learning model to read thousands of client-side signals, is available on Pro and Enterprise plans. You're only charged for requests that invoke `checkBotId()`\n\n, not for passive page views.\n\nUse the verified-bot fields that `checkBotId()`\n\nreturns alongside `isBot`\n\n. Check `isVerifiedBot`\n\nand `verifiedBotName`\n\nto allow a known agent, such as ChatGPT Operator, while still blocking everything else. For a trusted service that isn't in Vercel's verified bot directory, add a bypass rule in the Vercel WAF rather than removing protection for the route.\n\nThis is expected. BotID runs JavaScript in the browser session to send challenge headers to the server, so a direct request from curl or a browser address bar has no headers and gets treated as a bot in production. To test a protected route, make a `fetch`\n\nrequest from a page inside your own application.", "url": "https://wpnews.pro/news/how-to-protect-your-ai-endpoints-with-vercel-botid", "canonical_source": "https://vercel.com/kb/guide/protect-ai-endpoints-with-vercel-botid", "published_at": "2026-05-31 01:06:00+00:00", "updated_at": "2026-05-31 01:15:47.717327+00:00", "lang": "en", "topics": ["ai-tools", "ai-infrastructure", "ai-safety", "ai-products", "ai-research"], "entities": ["Vercel", "Vercel BotID", "Vercel WAF", "AI SDK"], "alternates": {"html": "https://wpnews.pro/news/how-to-protect-your-ai-endpoints-with-vercel-botid", "markdown": "https://wpnews.pro/news/how-to-protect-your-ai-endpoints-with-vercel-botid.md", "text": "https://wpnews.pro/news/how-to-protect-your-ai-endpoints-with-vercel-botid.txt", "jsonld": "https://wpnews.pro/news/how-to-protect-your-ai-endpoints-with-vercel-botid.jsonld"}}