IPAbuse Developers

Quickstart

Get up and running with the IPAbuse API in under 5 minutes. You will need an API key — grab one for free at ipabuse.org/settings.

Step 1 — Get your API key

  1. Create a free account or log in.
  2. Go to Settings → API Keys and click Create New Key.
  3. Copy the key — it is only shown once.

Step 2 — Look up an IP address

Send a GET request to /v1/ip/{ipAddress}/:

cURL
curl https://api.ipabuse.org/v1/ip/1.2.3.4/ \
  -H "X-API-Key: YOUR_API_KEY"

Example response

JSON
{
  "success": true,
  "data": {
    "ipAddress": "1.2.3.4",
    "found": false,
    "reputationScore": 100,
    "abuseScore": 100,
    "riskLevel": "LOW",
    "totalReports": 0,
    "verifiedReports": 0,
    "activeReportCount": 0,
    "verifiedReportCount": 0,
    "isWhitelisted": false,
    "reports": [],
    "country": null,
    "city": null,
    "region": null,
    "isp": null,
    "organization": null,
    "asn": null,
    "whoisData": null,
    "reputation": {
      "risk_score": 0,
      "risk_level": "low",
      "confidence": "low",
      "scoring_version": "2.0"
    },
    "data_freshness": {
      "last_updated": null
    },
    "externalBlocklistHits": []
  }
}

A reputationScore of 100 means clean; 0 is the worst. See IP Reputation for full score semantics.

Step 3 — Report an IP (optional)

Submit reports with a JWT cookie or an API key with the REPORT scope. Use a category slug from GET /v1/categories; severity is an integer from 1 to 10:

cURL
curl -X POST https://api.ipabuse.org/v1/ip/report \
  -H "X-API-Key: YOUR_REPORT_SCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAddress": "1.2.3.4",
    "categorySlug": "spam",
    "description": "Sending spam from this IP",
    "severity": 2
  }'

Eligible authenticated reports may earn credits. See Credits for earning rules.

Step 4 — Retrieve reputation entries (optional)

The plugin blocklist endpoint returns reputation entries for a category whose score is at least min_score. It supports JSON or plain-text output. Inspect each entry's risk level and apply your own blocking policy rather than blocking every returned IP:

cURL
curl "https://api.ipabuse.org/v1/plugin/blocklist?category=SPAM&min_score=0&format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Next steps