API reference

Plain REST over HTTPS, JSON by default. Base URL https://isipsafe.com/api/v1. There is also an OpenAPI 3.1 spec if you would rather generate a client.

Authentication

Lookups (check, reports, check-block) work without a key, up to 400 per 24 hours per client address. Reporting, bulk uploads, the blocklist and clearing reports need a key, and a free account's key raises lookups to 10,000 per 24 hours (no limit on Enterprise). Sign in to get one (free), then add it to the URL as key:

https://isipsafe.com/api/v1/blocklist?key=sl_your_key_here&format=txt

If you prefer to keep it out of URLs (and out of proxy logs), send it as a header instead. Both work on every endpoint:

Authorization: Bearer sl_your_key_here

A wrong key returns 401 instead of quietly falling back to the anonymous allowance, so typos are obvious. The examples below assume export ISIPSAFE_KEY=sl_your_key_here.

Responses and errors

Successful responses wrap the payload in data. Errors look like this, with a matching HTTP status:

{ "errors": [ { "detail": "ip: that is not a valid IPv4 or IPv6 address", "status": 422 } ] }

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 also has Retry-After in seconds. Limits are on the pricing page.

Everything we know about one address.

curl -s "https://isipsafe.com/api/v1/check?ip=203.0.113.50&verbose&key=$ISIPSAFE_KEY"

{
  "data": {
    "ipAddress": "203.0.113.50",
    "isPublic": true,
    "isWhitelisted": false,
    "isTor": false,
    "hostnames": ["scanner-7.example.net"],
    "ipVersion": 4,
    "abuseConfidenceScore": 86,
    "confidenceBand": "High",
    "totalReports": 41,
    "numDistinctUsers": 6,
    "firstReportedAt": "2026-10-02T08:14:11Z",
    "lastReportedAt": "2026-10-25T03:12:40Z",
    "categories": ["port-scan", "brute-force", "ssh"],
    "categoryIds": [14, 18, 22],
    "countryCode": "NL",
    "countryName": "Netherlands",
    "region": "North Holland",
    "city": "Amsterdam",
    "asn": 64496,
    "isp": "Example Hosting B.V.",
    "link": "https://isipsafe.com/ip/203.0.113.50",
    "reports": [ { "reportedAt": "...", "comment": "...", "categories": ["ssh", "brute-force"], "reporterType": "verified", "reporterCountryCode": "DE" } ]
  }
}

Report one address. Send form fields or JSON. Without a key the API answers 401.

curl -s "https://isipsafe.com/api/v1/report?key=$ISIPSAFE_KEY" \
  -d ip=203.0.113.50 -d categories=ssh,brute-force -d comment="sshd: 212 failed logins"

curl -s https://isipsafe.com/api/v1/report -H "Content-Type: application/json" \
  -d '{"ip":"2001:db8::7","categories":["web-app-attack","sql-injection"],"comment":"UNION SELECT in ?id="}'

{ "data": { "ipAddress": "203.0.113.50", "abuseConfidenceScore": 87, "link": "https://isipsafe.com/ip/203.0.113.50" } }

The same reporter can report the same address once per 15 minutes. A repeat returns 429; treat it as success. Reporting 127.0.0.2 always returns a 429, so you can test how your script handles it. Allowlisted addresses (public DNS resolvers and the like) are rejected with 422.

Up to 10,000 reports in one CSV. Columns IP,Categories,ReportDate,Comment, header row optional. Send it as the csv field of a multipart form, or as the raw body.

curl -s "https://isipsafe.com/api/v1/bulk-report?key=$ISIPSAFE_KEY" -F [email protected]

{ "data": { "savedReports": 812, "invalidReports": [ { "error": "unknown category \"99\"", "input": "198.51.100.4", "rowNumber": 14 } ] } }

Reports for one address, newest first, paginated.

The response includes total, lastPage, nextPageUrl and previousPageUrl.

All reported addresses inside a network. IPv4 blocks up to a /16, IPv6 up to a /48.

curl -s "https://isipsafe.com/api/v1/check-block?network=203.0.113.0/24&maxAgeInDays=60"

The addresses with the highest confidence, ready for a firewall. /blacklist is an alias for tools that expect that name.

curl -s "https://isipsafe.com/api/v1/blocklist?key=$ISIPSAFE_KEY&format=txt&confidenceMinimum=90&exceptCountries=GB"

Deletes every report you (this key's account) filed against an address. Use it when you reported something by mistake.

curl -s -X DELETE "https://isipsafe.com/api/v1/clear-address?key=$ISIPSAFE_KEY&ip=203.0.113.50"

All categories with their code (slug), name, group, description and legacy numeric ID. Also on the categories page.

Coming from another service?

Field names (ip, categories, comment, maxAgeInDays, confidenceMinimum), the response fields (abuseConfidenceScore, totalReports, numDistinctUsers, lastReportedAt) and category numbers 1 to 23 follow the conventions most abuse databases use. In most scripts, changing the base URL and the key is enough.