BotBlocker includes a dedicated API that enables deep, programmable, and highly flexible verification of all incoming visitors. This API allows developers and advanced users to integrate BotBlocker’s security logic into external systems, custom workflows, reverse proxies, load balancers, and specialized automation pipelines. By using the API, you can trigger real-time checks, apply additional filtering, and enforce security rules long before a request reaches WordPress.
The API performs a full server-side validation of the visitor, including BotBlocker’s internal detection layers such as IP analysis, DNS inspection, PTR checks, ASN lookups, user agent profiling, and behavior-based filtering. This guarantees consistent results even when requests bypass the browser or attempt to spoof parameters.
Most protection tools rely on client-side signals that can be faked or skipped entirely. With BotBlocker, the API runs all checks on the server, which means the verification process does not depend on JavaScript execution or browser behavior. Whether a visitor is a real user, a script, or an automated tool, the result is based on hard data collected at the network and application level.
You can integrate the API with firewall appliances, NGINX or Apache rewrite layers, Cloudflare Workers, load balancers, proxies, or external SaaS platforms. This makes it possible to enforce your WordPress security rules on infrastructure levels outside WordPress itself.
This kind of integration is especially useful when your infrastructure involves multiple layers of traffic handling. Instead of applying security rules only at the WordPress level, you can push that logic outward to the edges of your network. A request can be evaluated and blocked before it ever touches your application server, which reduces unnecessary load and keeps your stack cleaner.
All checks performed via the API fully match the logic used inside WordPress. This means you can run the same high-level protection anywhere: on remote servers, in background tasks, or in external applications that pre-screen visitors.
Having unified logic across all entry points eliminates gaps in your security coverage. When the same rules apply whether a check is triggered from inside WordPress or from an external proxy, there is no risk of inconsistency. A visitor that would be blocked inside WordPress will also be blocked when the API is called from any other system in your setup.
Large installations can call the API from a reverse proxy to block unwanted traffic before it reaches WordPress, reducing resource usage and improving performance.
When you operate a high-traffic site, even processing bad requests at the WordPress level takes time and server resources. By moving the check to the proxy layer and calling the API there, you stop unwanted visitors much earlier in the request lifecycle. This approach is particularly effective against scraping bots, credential stuffing tools, and other automated traffic that hits your site in large volumes.
If you operate a network of sites, you can centralize all traffic verification on a single BotBlocker instance and use its API from each node.
Managing security across many separate WordPress installations can be difficult when each one runs its own rules independently. With a centralized setup, all nodes in your network send verification requests to a single point. This gives you consistent protection across the entire network and makes it easier to update rules, review logs, and respond to threats from one place rather than managing each site separately.
The API can be used inside cron jobs, n8n workflows, CI/CD pipelines, or custom scripts to trigger IP checks, validate suspicious visitors, or automatically update blocklists.
Automation is one of the strongest reasons to use the API in your security setup. Instead of waiting for a human to notice suspicious activity, you can build workflows that detect patterns and react instantly. For example, if your monitoring system flags a spike in failed login attempts from a specific IP range, a custom script can query the API, confirm the threat, and add those addresses to the blocklist without any manual steps involved.
The API returns unified JSON responses that include visitor status, detailed check results, and actionable fields: allowed, blocked, suspicious, reason, rule source, and additional metadata. This lets your external systems interpret results reliably and apply automated decisions.
The structured format of each response makes it straightforward to build logic around the output. Your systems do not need to parse free-form text or handle unpredictable data shapes. Every response follows the same schema, so you can write integration code once and trust that it will work consistently regardless of what triggered the check or what the result was.
Each response from the API includes several fields that cover different aspects of the verification result. The status field tells you the main outcome for the visitor. The reason field explains what triggered that outcome. The rule source field shows which layer of BotBlocker’s detection was responsible. Additional metadata fields can include information such as the ASN, the country of origin, the PTR record result, and the user agent classification.
This level of detail is useful not just for making blocking decisions in real time, but also for logging and analysis. You can store the full response for each request and later review patterns, identify recurring threats, or fine-tune your security rules based on actual data from your traffic.
The API is lightweight, fast, and optimized for high throughput, making it suitable for enterprise-level traffic and batch processing scenarios.
Performance matters when every incoming request goes through a verification step. A slow or resource-heavy API would create bottlenecks and hurt user experience. BotBlocker’s API is built to handle large request volumes without adding noticeable latency. Whether you are running a single busy site or routing traffic from an entire network through one verification endpoint, the API holds up under load.
Access to the API is controlled through authentication tokens that you generate from within BotBlocker. Each token is tied to your installation and can be scoped or rotated as needed. This keeps your verification endpoint secure and ensures that only your authorized systems can trigger checks.
Setting up authentication is straightforward. Once you have a token, you include it in the request header when calling the API. Your external system sends the visitor data along with the token, and the API processes the request using BotBlocker’s full detection stack.
A typical API call includes the visitor’s IP address and user agent as the minimum required fields. Depending on your setup, you can also pass additional signals such as request headers, referrer data, or custom identifiers. The more context you provide, the more precise the verification result will be.
Requests are sent over standard HTTPS, and the API accepts data in JSON format. This makes it compatible with virtually any programming language or platform that can make HTTP requests, from Python scripts to Node.js services to low-level shell scripts running on a proxy server.
Once your system receives the JSON response from the API, the next step is to act on the result. Most integrations follow a simple pattern: if the status is allowed, the request continues normally. If the status is blocked or suspicious, the system takes a defined action such as returning an error page, redirecting the visitor, or logging the event for review.
You can also build more nuanced handling based on the reason and rule source fields. For instance, visitors flagged as suspicious rather than fully blocked might be sent through an additional verification step, such as a challenge page, before being allowed to continue. This gives you control over how strict or lenient your response is for different categories of visitors.
One of the most common deployment patterns is calling the API from an NGINX or Apache configuration using a rewrite rule or an auth request module. This allows the web server to query BotBlocker before passing the request to WordPress. If the API returns a blocked status, the web server can reject the request immediately without involving PHP or the WordPress stack at all.
Cloudflare Workers run at the edge, before traffic even reaches your server. By calling the API from a Worker, you can apply BotBlocker’s verification logic at the CDN level. This means bad traffic can be stopped at a global network edge, which is the earliest possible point in the request path and the most efficient place to block at scale.
If your setup uses a load balancer to distribute traffic across multiple backend servers, the API can be called at the load balancer level. This way, verification happens once per request regardless of which backend server it would be routed to. The result determines whether the request is forwarded to any backend at all or dropped immediately.
