Skip to content

Making a request

BotGuard’s API suite empowers customers to protect and optimize their web infrastructure with ease. Whether you’re looking to safeguard websites against malicious bots, manage load balancing, or monitor traffic in real-time, BotGuard's APIs provide a reliable and scalable path to achieve your goals. With intuitive endpoints and documentation improvements, BotGuard enables seamless integration, allowing users to enhance security and improve performance. It also provides an easy method for BotGuards partners to manage their customer's assets. This document provides examples of how to make requests to BotGuard's API endpoints.

It may be helpful to refer to Namespace structures, which demonstrates how objects are structured.

Managing users

The following examples demonstrate how you can manage users associated with your account. With this information, partners can have a clear overview of each customer and the domains that they manage, which is essential for additonal tasks, such as setting up of domain limits.

List users

Using the Get User API endpoint this example is an operation returning user objects, which contains information about Users associated with the current Account that the current user can manage: 

curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/user' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
The current user can simply view returned users using this operation, or proceed to find out information about the user, such as account statistics, or their assets. Additionally, the user may proceed to edit or delete returned user accounts.

Get a user's ID

Using the Get User API endpoint this example operation enables you to find a single user's ID (email address):

curl -X GET https://<GATEKEEPER-IP:PORT>/v1.0/user 
--header 'accept: application/json' 
--header 'Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’

Create a user

Using the Add User API endpoint this example operation enables you to create a single new user:

curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/user' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Considerations about user creation

There are considerations why you might want to use users at scale, rather than just creating one user for all assets:

  • Statistics reporting can be done on per User object, which means that as you scale, asset/website responsibility can be divided between users.
  • Requesting statistics from a User object reports on statistics across all assets/websites belonging to that user. Refer to the Get user traffic statistics example below.
  • BotGuard dashboard access is granted on a User object basis. If you only want some users to access the dashboard and the associated Custom rules, then create users at scale.

Manage devices

Add a device account to a user account

This example demonstrates how to add a device using its IP address. It is added to the default owner of the API key used in the call, unless otherwise stated like in this example. The device is also named and the zone name provided (if available). Optionally, tags can also be added.

curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/device' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data-urlencode 'user_id=user@domain.com' \
--data-urlencode 'name=Load Balancer #4' \
--data-urlencode 'zone=uk-lon1' \
--data-urlencode 'tag=virtual-lb'

Manage servers

Add a server account to a user account

This example demonstrates how to add a server using its IP address. The server is added to the default owner of the API key used in the call, unless otherwise stated like in this example. The server is also named and the zone name provided (if available). 

curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/server' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data-urlencode 'ip=123.123.123.123' \
--data-urlencode 'user_id=user@domain.com' \
--data-urlencode 'name=vps1.example.com' \
--data-urlencode 'zone=us-east1' \
--data-urlencode 'tag=vps'

Manage websites

Asynchronous API

BotGuard is currently working on implementing an Asynchronous API. This means that you should be able to specify a call-back URL. When a status of a website changes in BotGuard, you will receive a call back to the URL you specified.

Calls made with application/x-www-form-urlencoded have limited scope and are suitable for simple integrations that require embedding of BotGuard UI. Calls made with application/json can define the complete website schema. Subsequently this means that they are suitable for advanced API-first integrations, especially where partners wish to implement rules editing in their own control panel and manage them in BotGuard via the API.

There are two methods of creating/updating websites using the GateKeeper API. The choice depends on your Content-Type header, which can be either:

  • application/json
  • application/x-www-form-urlencoded

BotGuard recommends using the application/json Content-Type as this facilitates managing traffic rules and configuration of the load balancer within your hosting panel.

Create a website

This example operation creates a website and sets all the associated parameters for the created website:

curl --location --request POST 'https://<GATEKEEPER-IP:PORT>/v1.0/website' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data '{
    "domain": "example.com",
    "subdomain": [],
    "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ip": [
        "xxx.xx.xxx.xx"
    ],
    "tag": [
        "DC1"
    ],
    "status": "online",
    "settings": {
        "rulesets": {
            "bitrix": false,
            "cpanel": false,
            "dokuwiki": false,
            "drupal": false,
            "joomla": false,
            "nextcloud": false,
            "prestashop": false,
            "wordpress": true,
            "xenforo": false
        },
        "rules": {
            "content_scrapers": "deny",
            "emulated_humans": "deny",
            "humans": "grant",
            "search_engines": "grant",
            "security_issues": "deny",
            "services_and_payments": "grant",
            "social_networks": "grant",
            "suspicious_behaviour": "captcha"
        },
        "loadbalancer": {
            "upstreams_use_https": true,
            "enable_http3": true,
            "force_https": true,
            "cache_static_files": true,
            "cache_dynamic_pages": false,
            "ddos_protection": false,
            "ddos_protection_advanced": false,
            "botguard_protection": true,
            "certs_issuer": "buypass",
            "force_subdomains_redirect": true
        }
    }
}'

Update a website

This example operation updates an existing website by enabling the configuration of the associated parameters:

curl --location --request PUT 'https://<GATEKEEPER-IP:PORT>/v1.0/website/example.com' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data '{
    "domain": "example.com",
    "subdomain": ["www"],
    "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ip": [
        "xxx.xx.xxx.xx"
    ],
    "tag": [
        "DC1"
    ],
    "status": "online",
    "callbackUrl": "http://<address>.com:8081/callback/website",
    "settings": {
        "rulesets": {
            "bitrix": false,
            "cpanel": false,
            "dokuwiki": false,
            "drupal": false,
            "joomla": false,
            "nextcloud": false,
            "prestashop": false,
            "wordpress": true,
            "xenforo": false
        },
        "rules": {
            "content_scrapers": "deny",
            "emulated_humans": "deny",
            "humans": "grant",
            "search_engines": "grant",
            "security_issues": "deny",
            "services_and_payments": "grant",
            "social_networks": "grant",
            "suspicious_behaviour": "captcha"
        },
        "loadbalancer": {
            "upstreams_use_https": true,
            "enable_http3": true,
            "force_https": true,
            "cache_static_files": true,
            "cache_dynamic_pages": false,
            "ddos_protection": false,
            "ddos_protection_advanced": false,
            "botguard_protection": true,
            "certs_issuer": "letsencrypt",
            "force_subdomains_redirect": true
        }
    }
}'

Website lookup

Perform a lookup on a specific domain name to return all the current settings and rules for that website:

curl -G 'https://<GATEKEEPER-IP:PORT>/v1.0/website' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data-urlencode 'domain=example.com'

Get website traffic statistics

Using the Website Statistics API endpoint this example operation retrieves traffic statistics for all websites belonging to a particular user. This includes total hits per website, information on whether the hits were permitted or blocked, and details on hits that triggered mitigation.

curl -X GET https://<GATEKEEPER-IP:PORT>/v1.0/website/example.com/statistics 
--header 'accept: application/json'
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’

Enable/disable website protection

For partners, if one of their customer’s websites reaches their hit limit, the partner may disable protection and enable monitoring mode only. To execute this change for a single website, use the API endpoint Changes a website account.

curl -X PUT https://GATEKEEPER-IP:PORT/v1.0/website/example.com 
--header 'accept: application/json' 
--header 'Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' 
-d 'status=paused’

This endpoint enables partners to monitor hit counts and apply limits based on either the number of requests per individual website, or the aggregate total across all websites that a customer has configured. Set the status parameter to paused to disable protection and enable monitoring mode only. In the future, set the status to online to reverse this request at any time and enable protection for the website again.