Version 2.4.8 · latest

Bot settings bot-settings

Platform-wide bot management: the action per class (search engine / monitor and tool / automation tool / AI crawler / headless browser / malicious bot) and for fake crawlers, the challenge kind, behaviour score bands, protected endpoints and exceptions; admin only. Headless browser, malicious bot and fake crawler actions plus behaviour scoring belong to the paid feature WAF enhanced. Each site may override per class in the site config field bot.

Pick an endpoint to see its example call on the right.

ProtectionAuthentication: Admin only2 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/bot-settingsGet bot settings

Authentication: Admin only

PUT/api/v2/bot-settingsUpdate bot settings

Authentication: Admin only

Request body application/json

FieldTypeDescription
actionsobject Action per class; defaults are allow for search engines and monitors/tools, log for automation tools and AI crawlers, challenge for headless browsers and block for malicious bots and fake crawlers. headless, malicious and fake belong to WAF enhanced.
challengestring Challenge kind used when the action is challenge - js (invisible), slide, rotate, click or captcha (default js).
Values ["js","slide","rotate","click","captcha"]
enabledboolean Master switch; false = no site does bot detection.
enhancedstring WAF enhanced state - full (active), readonly (expired but within the read-only buffer, License.readonly_days, 7 days by default; enhanced items still work but are read-only) or basic (not purchased or past the buffer; headless browsers, malicious bots and fake crawlers are treated as ordinary visitors and not scored, settings kept); ignored on update.
Values ["full","readonly","basic"]
exceptionsobject[] Exceptions - matching requests skip bot detection (at least one of path, cidr and ja4; several in one entry must all match).
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (the version of the node.global config key, shared with CC and WAF settings; use 1970-01-01T00:00:00Z when the read value is null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
protectstring[] Protected endpoints (path prefixes such as /login, WAF enhanced) - requesting them without loading a page first adds to the score.
scoreobject Behaviour score bands (WAF enhanced, 0-100) - below js pass; js to slide invisible challenge; slide to block challenge by kind; from block act as a malicious bot. Requires js < slide < block. A visitor who passes a challenge scores 0 for 30 minutes.
updated_atstring Version in the response (updated_at of the node.global config key; null if never changed); ignored on update.

Bot settings object

FieldTypeDescription
actionsobject Action per class; defaults are allow for search engines and monitors/tools, log for automation tools and AI crawlers, challenge for headless browsers and block for malicious bots and fake crawlers. headless, malicious and fake belong to WAF enhanced.
challengestring Challenge kind used when the action is challenge - js (invisible), slide, rotate, click or captcha (default js).
Values ["js","slide","rotate","click","captcha"]
enabledboolean Master switch; false = no site does bot detection.
enhancedstring WAF enhanced state - full (active), readonly (expired but within the read-only buffer, License.readonly_days, 7 days by default; enhanced items still work but are read-only) or basic (not purchased or past the buffer; headless browsers, malicious bots and fake crawlers are treated as ordinary visitors and not scored, settings kept); ignored on update.
read-onlyValues ["full","readonly","basic"]
exceptionsobject[] Exceptions - matching requests skip bot detection (at least one of path, cidr and ja4; several in one entry must all match).
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (the version of the node.global config key, shared with CC and WAF settings; use 1970-01-01T00:00:00Z when the read value is null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
protectstring[] Protected endpoints (path prefixes such as /login, WAF enhanced) - requesting them without loading a page first adds to the score.
scoreobject Behaviour score bands (WAF enhanced, 0-100) - below js pass; js to slide invisible challenge; slide to block challenge by kind; from block act as a malicious bot. Requires js < slide < block. A visitor who passes a challenge scores 0 for 30 minutes.
updated_atstring Version in the response (updated_at of the node.global config key; null if never changed); ignored on update.
read-only

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command