PortWallTalk to an expert ↗
Home / Docs / API reference

API reference: bot protection

Read and change the bot-protection settings: the browser check, its sites and exempt paths, TLS fingerprinting and the actions for bot clusters and credential stuffing.

Get the bot-protection settings

GET /api/bot-protection

Needs a Viewer or Admin key.

Replies

Status Meaning Body
200 OK BotProtectionView

Reply fields

Field Type Description
underAttackAll boolean True to show the browser check to every visitor of every site. Always present.
underAttackSites list of string Names of the sites whose visitors are all shown the browser check. Use names from sites. Not needed when underAttackAll is true. Always present.
exemptPaths list of string Paths the browser check never applies to, on every site, for example /api/ or /webhooks/ (API clients and webhooks cannot run the check). Each starts with /, and has no spaces, quotes, braces, # or backslashes. /.well-known/ is always left out. Always present.
difficulty integer How much work the browser check asks of a visitor's browser, from 16 (normal) to 22 (strongest). Default 18. Always present.
clearanceMinutes integer How long, in minutes, a visitor who passed the check is left alone, from 5 to 1440 (24 hours). Default 30. Always present.
ja4 boolean True to record each visitor's TLS fingerprint, which lets PortWall recognise one bot that uses many addresses. Default false. Always present.
botClusterAction DetectionAction What happens to the addresses of one bot spread over many addresses once it is detected. Default Challenge. Always present. One of Alert, Challenge, Block.
credentialStuffingAction DetectionAction What happens to the addresses behind a credential-stuffing attack on a login page once it is detected. Default Challenge. Always present. One of Alert, Challenge, Block.
flaggedMinutes integer How long, in minutes, an address that a detection acted on stays challenged or blocked, from 5 to 10080 (7 days). Default 60. Always present.
sites list of string The names of the sites on this installation, which you can use in underAttackSites. Read-only; ignored if you send it. Always present.
crawlers BotCrawlersView The search-engine crawler addresses that are never checked. Read-only. Always present.
feedChallengeRanges integer How many address ranges from threat-intelligence feeds are set to Challenge, and so are shown the browser check. Null when it cannot be read. Read-only.
flagged list of FlaggedVisitor The addresses that detections are challenging or blocking now, soonest to expire first (at most 200). Read-only. Always present.
premium boolean True when your licence includes bot protection. When false the settings are saved but take effect only once your edition includes it. Read-only. Always present.
plan string The name of your licence edition. Read-only. Always present.

Change the bot-protection settings

PUT /api/bot-protection

Needs an Admin key.

Fields left out keep their current value, except underAttackSites and exemptPaths, which are replaced (empty when left out).

Request body: BotProtectionDto

Field Type Description
underAttackAll boolean True to show the browser check to every visitor of every site.
underAttackSites list of string Names of the sites whose visitors are all shown the browser check. Use names from sites. Not needed when underAttackAll is true. Optional.
exemptPaths list of string Paths the browser check never applies to, on every site, for example /api/ or /webhooks/ (API clients and webhooks cannot run the check). Each starts with /, and has no spaces, quotes, braces, # or backslashes. /.well-known/ is always left out. Optional.
difficulty integer How much work the browser check asks of a visitor's browser, from 16 (normal) to 22 (strongest). Default 18. Optional.
clearanceMinutes integer How long, in minutes, a visitor who passed the check is left alone, from 5 to 1440 (24 hours). Default 30. Optional.
ja4 boolean True to record each visitor's TLS fingerprint, which lets PortWall recognise one bot that uses many addresses. Default false.
botClusterAction DetectionAction What happens to the addresses of one bot spread over many addresses once it is detected. Default Challenge. Optional. One of Alert, Challenge, Block.
credentialStuffingAction DetectionAction What happens to the addresses behind a credential-stuffing attack on a login page once it is detected. Default Challenge. Optional. One of Alert, Challenge, Block.
flaggedMinutes integer How long, in minutes, an address that a detection acted on stays challenged or blocked, from 5 to 10080 (7 days). Default 60. Optional.

Replies

Status Meaning Body
200 OK SettingsSaved
400 Bad Request ApiError

Reply fields

Field Type Description
saved boolean True when the settings were stored. Always present.
applying boolean True when PortWall is applying the settings in the background. The change is in force once the apply status reports it completed. Always present.
applySeq integer A number to wait for: the settings are in force when completed from GET /api/config-apply/status reaches this number. Always present.
pending string A note when the settings are saved but cannot be applied yet. Empty when there is nothing waiting. Can be null.
Updated 2026-10-27Something unclear or missing? Tell us.