Fail2Ban

Updated Oct 4, 2026 Markdown

POST /api/v1/fail2ban/ban

Manually ban an IP

Adds an IP (or, in an HTTP-facing jail, a network) to the specified jail's banned set immediately. A whitelisted address answers 409 IP_WHITELISTED; the caller's own address, or a network covering it, answers 422 SELF_LOCKOUT.

Body fields:

Field Type Required Notes
ip string yes —
jail_name string yes —

Request body example:

JSON
{
  "ip": "string",
  "jail_name": "string"
}

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/fail2ban/ban

DELETE /api/v1/fail2ban/ban/{jail_name}/{ip}

Unban single IP from a jail

Removes the IP from the named jail. Other jails are unaffected.

Path parameters:

Name Type Required Notes
jail_name string yes —
ip string yes —

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/ban/{jail_name}/{ip}

GET /api/v1/fail2ban/banned

List currently banned IPs

Aggregated banned list across every enabled jail.

Responses:

Status Schema Description
200 ApiSuccess_list_BannedIPEntry__ Successful Response

Response example (200):

JSON
{
  "data": [
    {
      "ip": "...",
      "jail": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/banned

GET /api/v1/fail2ban/jails

List fail2ban jails

Every jail definition (enabled + disabled), with current banned IP count.

Responses:

Status Schema Description
200 ApiSuccess_list_JailStatusResponse__ Successful Response

Response example (200):

JSON
{
  "data": [
    {
      "banned_ips": "...",
      "bantime": "...",
      "currently_banned": "...",
      "enabled": "...",
      "filter": "...",
      "findtime": "...",
      "logpath": "...",
      "maxretry": "...",
      "name": "...",
      "total_banned": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails

GET /api/v1/fail2ban/jails/{jail_name}

Get fail2ban jail by name

Detail view of one jail — filters, action, banned list.

Path parameters:

Name Type Required Notes
jail_name string yes —

Responses:

Status Schema Description
200 ApiSuccess_JailStatusResponse_ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {
    "banned_ips": [
      "..."
    ],
    "bantime": 0,
    "currently_banned": 0,
    "enabled": false,
    "filter": "string",
    "findtime": 0,
    "logpath": "string",
    "maxretry": 0,
    "name": "string",
    "total_banned": 0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}

PUT /api/v1/fail2ban/jails/{jail_name}

Update fail2ban jail

Patch maxretry / findtime / bantime / log paths.

Path parameters:

Name Type Required Notes
jail_name string yes —

Body fields:

Field Type Required Notes
bantime integer no —
findtime integer no —
maxretry integer no —

Request body example:

JSON
{
  "bantime": 60.0,
  "findtime": 60.0,
  "maxretry": 1.0
}

Responses:

Status Schema Description
200 ApiSuccess_JailStatusResponse_ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {
    "banned_ips": [
      "..."
    ],
    "bantime": 0,
    "currently_banned": 0,
    "enabled": false,
    "filter": "string",
    "findtime": 0,
    "logpath": "string",
    "maxretry": 0,
    "name": "string",
    "total_banned": 0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}

POST /api/v1/fail2ban/jails/{jail_name}/disable

Disable fail2ban jail

Deactivates the jail and reloads fail2ban. Existing bans on the jail are released.

Path parameters:

Name Type Required Notes
jail_name string yes —

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}/disable

POST /api/v1/fail2ban/jails/{jail_name}/enable

Enable fail2ban jail

Activates the jail and reloads fail2ban.

Path parameters:

Name Type Required Notes
jail_name string yes —

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/jails/{jail_name}/enable

GET /api/v1/fail2ban/status

Fail2Ban service status

Returns whether fail2ban daemon is running, version, jail count, total banned IPs.

Responses:

Status Schema Description
200 ApiSuccess_Fail2BanStatusResponse_ Successful Response

Response example (200):

JSON
{
  "data": {
    "active": false,
    "jail_count": 0,
    "jails": [
      "..."
    ],
    "total_banned": 0,
    "version": ""
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/status

POST /api/v1/fail2ban/unban-all

Unban every IP across every jail

Bulk action — clears every active ban in every jail. Whitelist is untouched. The message carries the number of released addresses.

Responses:

Status Schema Description
200 MessageResponse Successful Response

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/unban-all

GET /api/v1/fail2ban/whitelist

Get fail2ban whitelist

IPs permanently exempt from every jail's ban logic. Response data: a list of whitelisted IP strings.

Responses:

Status Schema Description
200 ApiSuccess_list_str__ Successful Response

Response example (200):

JSON
{
  "data": [
    "string"
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/whitelist

POST /api/v1/fail2ban/whitelist

Add IP to whitelist

Exempt an IP from all fail2ban bans. Existing bans on the IP are released.

Body fields:

Field Type Required Notes
ip string yes —

Request body example:

JSON
{
  "ip": "string"
}

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/fail2ban/whitelist

DELETE /api/v1/fail2ban/whitelist/{ip}

Remove IP from whitelist

The IP returns to normal ban-eligible state.

Path parameters:

Name Type Required Notes
ip string yes —

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/fail2ban/whitelist/{ip}
Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket