IP Reputation API — REST API v1
Abuse score, blacklist matches, VPN/proxy/Tor/hosting type, ASN and location for any IPv4 or IPv6 address in one JSON response — plus abuse reporting and the whole blocklist as a firewall feed. Key-based auth, 1,000 free requests a day.
curl -H "Key: YOUR_API_KEY" https://ip-db.com/api/v1/check/8.8.8.8
- No credit card
- IPv4 and IPv6
- Key-based auth
What the API gives you
IP reputation & abuse score
A 0–100 score with its breakdown: 44 threat feeds, community reports, DNSBL, history and /24 neighbourhood.
Blacklist & blocklist API
Every matching list by name; the whole pool as paginated JSON or as plain text for firewalls (EDL, Threat Feed).
Proxy, VPN & Tor detection
networkType: residential, datacenter, vpn, tor — for fraud checks in sign-up and checkout flows.
Free tier
1,000 requests a day, 10,000 with a verified email. No credit card.
OpenAPI 3.1
/openapi.json — for Postman, code generators and AI agents such as GPT Actions.
MCP
A remote MCP server for Claude, ChatGPT and other MCP clients: https://ip-db.com/mcp
Authentication
Generate an API key from your dashboard and send it on every request as the Key header (or a ?key= query parameter). You'll only see the key once, at creation time — store it somewhere safe.
Every endpoint returns 401 if the key is missing or invalid.
Rate limits
The limit is per account, not per key — every key you create draws from the same pool. Unverified accounts get 1,000 requests a day, verified ones 10,000; /check and /report are counted separately.
Daily quotas reset every day at 00:00 Turkey time (UTC+3), the same day boundary as the "today" counter in your dashboard. Reports (POST /report) have a counter of their own and do not use up your lookup quota.
| Endpoint | Limit |
|---|---|
| GET /api/v1/check/<ip> | 1,000 – 10,000 / day |
| POST /api/v1/report | 1,000 – 10,000 / day (separate counter) |
| GET /api/v1/blacklist | 60 /hour |
| GET /api/v1/feed.txt | 60 /hour |
Attribution (optional)
IP-DB is free and will stay free. If you show our data in a product, dashboard or open-source project, a link to ip-db.com in your docs helps keep the service running and helps others find it. If your integration is public, tell us and we will gladly list it on the integrations page.
Look up an IP
GET/api/v1/check/<ip>Returns the full intelligence report for the given IP — confidence score, location, ASN, blacklist matches, DNSBL results and community reports.
| Field | Type | Description |
|---|---|---|
| ipAddress | string | The queried IP address |
| ipVersion | integer | 4or6 |
| isPrivate | boolean | true for private/reserved ranges — other fields are not computed in that case |
| abuseConfidenceScore | integer | 0–100confidence score |
| scoreLabel | string | clean · low · suspicious · critical |
| scoreBreakdown | object | Which evidence the score rests on: feeds, reports, dnsbl (live lookup), liftedListing (residual of a listing since lifted) and neighbourhood (state of the surrounding /24). Their sum is capped at 100. |
| liftedListing | object | null | Present when the address left the lists within the last 60 days: delistedAt, priorScore, cycles, daysSince. null once the address is listed again — live matches govern then. |
| prefixNeighbourhood | object | null | How much of the surrounding /24 is listed; null for IPv6. A small share contributes nothing to the score. |
| countryCode / countryName / city | string | null | Geolocation; null when it cannot be resolved |
| asn / asnOrg / isp | integer/string | null | Autonomous system and network owner |
| abuseContact | object | null | The network's abuse mailbox from its RDAP record (email, name, handle). null when the record names no contact in the "abuse" role. |
| totalReports / distinctReporters | integer | Community report counts |
| lastReportedAt | string | null | ISO 8601 UTC |
| blacklistSources | string[] | Names of the automated threat feeds that matched |
| reportUrl | string | The public IP-DB report for this address (in the key owner's language). Show it in alerts or dashboards and your team is one click from the evidence. |
| dnsbl | object[] | Only the DNSBL zones that returned a listing (zone, label, listed) |
Report an IP
POST/api/v1/reportReports an IP address for abuse. Repeated reports from the same account contribute more strongly to the confidence score.
Report the addresses you block, automatically
If you run a WAF, fail2ban or a SIEM, every address you block can be reported with a single line. Reports do not use your lookup quota, and they sharpen the score for everyone who sees the same attacker. An example fail2ban action:
Then add ipdb next to %(action_)s in the jail's action. Form fields and a JSON body are accepted alike.
| Field | Required | Description |
|---|---|---|
| ip | Yes | A public, non-private IPv4/IPv6 address |
| categories | Yes | Array or comma-separated string; at least one valid category key(↓) |
| comment | No | Free text — log excerpt, timestamps, etc. |
Valid category keys:brute_force, port_scan, web_attack, ssh_abuse, spam, ddos, malware, fraud, phishing, exploit, vuln_scan, credential_stuffing, iot_abuse, web_spam, ransomware, cryptomining_abuse, bad_bot, open_proxy
Blacklist Pool
GET/api/v1/blacklistReturns the current blacklist pool aggregated from our automated feeds, paginated.
| Param | Default | Description |
|---|---|---|
| page | 1 | 1-indexed page number |
| limit | 100 | Rows per page (max 1000) |
| category | — | Filter to a single category (optional) |
Valid category values:hijacked_network, botnet_c2, malware_c2, malicious_activity, attack_source, aggregated_high_confidence, aggregated_medium_confidence, compromised_host, tor_exit
Raw Text Feed
GET/api/v1/feed.txtFor devices that expect plain text instead of JSON: one IP per line. The highest-scoring redistributable addresses confirmed by at least two independent sources; capped per account (higher free on request) and counted toward your daily usage. The full list in bulk at /datasets. Paste it directly into the source URL field of Palo Alto External Dynamic Lists, FortiGate Threat Feed connectors, and similar. Authenticated via ?key= in the URL, since those interfaces don't support custom headers.
Supports category, min_score, limit, format and since. See Integrations for Palo Alto and FortiGate setup steps.
| Parameter | Value | What it does |
|---|---|---|
| format | plain | The default — one IP per line. Leave it out and you get exactly what you got before. |
| cidr · json · csv | The list with /32 and /128 suffixes, a JSON body, CSV. | |
| fortigate | FortiOS address objects (config firewall address / address6), ready to paste into the CLI. | |
| iptables | An ipset-based sh script — one rule, a hash lookup. Idempotent, safe from cron. | |
| nftables · mikrotik | An .nft file defining a table of its own; a RouterOS .rsc script. | |
| suricata · wazuh | Suricata rules (drop at 75+, alert below); a Wazuh CDB list (ip:score). | |
| since | 24h · 7d · 30m 2026-11-08T00:00:00Z |
Only addresses first listed inside that window, so a scheduled job need not pull the whole list every time. A value we cannot read is ignored and the full list is served — on a blocklist that is the safe way to fail — and X-Feed-Since says which happened. A flat list cannot express removals, so fetch the full list from time to time as well. |
OpenAPI & MCP
The whole API is described as OpenAPI 3.1 at /openapi.json — import it into Postman, generate a client, or add it as a GPT Action. For Claude, ChatGPT, Cursor and other MCP clients there is a keyless remote MCP server at https://ip-db.com/mcp with check_ip, check_blacklists and, for domains, domain_whois tools.
Frequently Asked Questions
Is the IP reputation API free?
Yes. A free key gets 1,000 requests a day, and 10,000 once you verify your email. No credit card.
What does the API return?
A 0–100 abuse confidence score with its breakdown, the blacklist sources that match, DNSBL listings, the network type (residential, hosting, VPN, Tor), ASN, ISP, geolocation, the RDAP abuse contact and community report counts.
Can I use it for fraud detection?
Yes. networkType and abuseConfidenceScore are enough to allow, challenge or block in sign-up, login and checkout flows; the thresholds are explained on the IP fraud score page.
How do I block IPs on my firewall with it?
/api/v1/feed.txt returns a plain-text blocklist with one IP per line; Palo Alto EDL, FortiGate Threat Feed, pfSense, OPNsense and MikroTik can read the URL directly.
Where does the data come from?
44 open threat-intelligence feeds (each listed with its licence on Data Sources), community abuse reports and live DNSBL queries. The pool refreshes every 30 minutes.
Is there an OpenAPI spec, and can AI agents use it?
Yes. The machine-readable spec is at /openapi.json, so agents built on ChatGPT, Claude or Gemini can call the API directly; for MCP-capable clients there is also an MCP server at /mcp.
Error codes
| Status | Meaning | Response body |
|---|---|---|
| 400 | Invalid IP, category, or missing field | {"error": "Invalid IP address."} |
| 401 | Key missing, invalid, or revoked | {"error": "Invalid or revoked API key."} |
| 429 | Daily/hourly limit exceeded | {"error": "ratelimit exceeded", "limit": "1000 per 1 day", "resetsAt": "…"} |