Firewall IPs API — v1

Authenticated access for reporting IPs and downloading blacklists. Every request requires both a valid API key and a caller IP that is allow-listed for that key. Contact an administrator to request a key.

Send your key via the X-API-Key header (preferred), or as an api_key query/POST parameter if your client can't set custom headers.

Setting up a CSF server

If your servers run CSF (ConfigServer Security & Firewall), you don't need to call the API directly — one command sets up automatic reporting and shared-blacklist blocking for every IP CSF blocks. Generate a unique API key per server first at Admin → API Keys — allow-list that server's IP and enable "can_report".

Quick install (recommended)

Run once per server, as root. Sets up the config, installs the reporting script, wires CSF's BLOCK_REPORT, subscribes to the shared blacklist, and restarts CSF/lfd — all in one step.

wget -O quick-install.sh https://firewallips.com/quick-install.sh
sudo bash quick-install.sh YOUR_API_KEY

Re-running this later (e.g. with the same key) is also how you update the reporting script — it always fetches the latest version and never touches your saved API key unless you pass --force.

sudo bash quick-install.sh YOUR_API_KEY

Rolling this out to many servers? Loop it over SSH from your own machine, e.g.:

for host in server1.example.com server2.example.com; do
    ssh root@$host "wget -qO quick-install.sh https://firewallips.com/quick-install.sh && bash quick-install.sh SERVER_SPECIFIC_KEY"
done

(Each server needs its own API key with that server's IP allow-listed — a shared key across servers with different IPs won't authenticate.)

Step-by-step install (alternative)

If you'd rather run — and inspect — each step separately instead of the combined quick-install script above:

wget -O create-firewallips-config.sh https://firewallips.com/create-firewallips-config.sh
sudo bash create-firewallips-config.sh YOUR_API_KEY

wget -O connect-csf.sh https://firewallips.com/connect-csf.sh
sudo bash connect-csf.sh

Managing many servers with this approach? See update_firewallips_script.sh — edit the server list at the top and run it from your own machine to update every server over SSH in one shot.

Raw API reference

For custom integrations, or firewalls other than CSF, use these endpoints directly.

POST /api/v1/report.php

Submit a new report for an IP or CIDR (CSF / general ecosystem).

Param	Required	Description
`ip`	Yes	IP address or CIDR range
`type`	No	Report type code (e.g. `sshd`, `portscan`, `manual`). Default: `manual`
`reason`	No	Free-text reason
`source`	No	Label identifying the reporting server

curl -X POST https://firewallips.com/api/v1/report.php \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "ip=203.0.113.55" \
  --data-urlencode "type=sshd" \
  --data-urlencode "reason=20 failed SSH logins in 10 minutes" \
  --data-urlencode "source=web1.example.com"

GET /api/v1/blacklist.php

Download the current active blacklist (entries not yet expired).

Param	Required	Description
`format`	No	`txt` (default, one IP/CIDR per line) or `json`

curl https://firewallips.com/api/v1/blacklist.php?format=json \
  -H "X-API-Key: YOUR_KEY"

GET /api/v1/reported.php

Download the full historical report log (never deleted).

Param	Required	Description
`format`	No	`txt` (default) or `json`
`since`	No	Only return reports on/after this UTC timestamp (`YYYY-MM-DD HH:MM:SS`)
`limit`	No	Max rows, default 5000, max 50000

POST /api/v1/wp-report.php

Submit a new report for an IP (WordPress ecosystem). Used by the FirewallIPs Security WordPress plugin — accepts a JSON request body rather than form-urlencoded fields.

Field	Required	Description
`ip`	Yes	IP address or CIDR range
`attack_type`	Yes	One of the plugin's detector types, e.g. `WP_BRUTEFORCE`, `WP_XMLRPC_ABUSE`, `WP_USER_ENUM`, `WP_VULN_SCAN`
`count`	No	Number of attempts this report represents
`first_seen` / `last_seen`	No	ISO 8601 timestamps — informational only; the server records its own receipt time
`site_hash`	No	Stable, non-reversible per-site identifier used only as a traceable source label
`evidence`	No	Free-text reason, pre-sanitized by the plugin

curl -X POST https://firewallips.com/api/v1/wp-report.php \
  -H "X-API-Key: YOUR_WP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.55","attack_type":"WP_BRUTEFORCE","count":12,"evidence":"12 failed logins in 5 min"}'

Reports submitted here are tagged as WordPress-ecosystem and appear in wp-blacklist.txt (and also in the general blacklist if the same IP is separately reported by a CSF-integrated server).

GET /api/v1/wp-blocklist.php

Download the current WordPress-specific blocklist — the counterpart to blacklist.php for the WordPress ecosystem.

Param	Required	Description
`limit`	No	Max entries returned, default 10000
`since`	No	Only return entries reported on/after this timestamp
`plaintext`	No	`1` for one IP per line (default for the plugin); omit for JSON

curl "https://firewallips.com/api/v1/wp-blocklist.php?plaintext=1" \
  -H "X-API-Key: YOUR_WP_KEY"

API key types

Keys are scoped when created: csf keys only authenticate against report.php / blacklist.php / reported.php; wordpress keys (prefixed fwipswp_) only authenticate against wp-report.php / wp-blocklist.php; universal keys work with both ecosystems. Each key must also have the caller's IP on its allow-list — requests from any other IP are rejected regardless of key validity.

Errors

All endpoints return JSON on error, with an HTTP status code:

401 — missing/invalid API key, caller IP not allow-listed, or key wrong ecosystem/permission
405 — wrong HTTP method for this endpoint
422 — invalid or missing parameters
500 — internal error