API Documentation
Integrate IP enrichment and threat intelligence into your applications with our free REST API.
Generate a client in any language:
- OpenAPI 3.1 specification:
/api/v1/openapi.json - Interactive Swagger UI:
/api/docs - Official client libraries: Python, Go, Node.js, PowerShell — downloadable directly from this site
- Threat-intel feeds: TAXII 2.1 · STIX 2.1 · MISP feed
- Try it without an account:
/api/v1/teaser(10 req/hour per IP, no key required)
Authentication
All API requests require authentication via an API key. Include your key in the X-API-Key header.
To obtain an API key, register for a free account and visit your profile page.
Rate Limits
All accounts start on the free tier. The default limits are:
| Endpoint | Limit | Scope |
|---|---|---|
| API lookups | 600 requests per hour | Per API key |
| Web lookups | 30 requests per hour | Per IP address |
| Login attempts | 10 attempts per hour | Per IP address |
Need higher API limits? Registered users can request a limit increase from their profile page. Requests are reviewed and approved on a case-by-case basis.
Rate limit information is included in every API response via headers:
IP Lookup
Retrieve enrichment data, geolocation, ISP information, and threat assessment for any public IP address.
/api/v1/lookup?ip={address}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ip | string | Yes | IPv4 or IPv6 address to look up |
Example Request
Example Response
Example Response — AI Agent Assessment populated
The ai_agent_assessment block is always present. When recorded signals describe agentic LLM traffic from a source, it surfaces a confidence band, the contributing signals, and the published methodology version. The block is additive — existing consumers that do not read this field are unaffected.
Response Fields
| Field | Description |
|---|---|
| ip | Queried IP address |
| ip_version | IP version (4 or 6) |
| country_code | ISO 3166-1 alpha-2 country code |
| country_name | Country name |
| region_name | Region or state name |
| city | City name |
| latitude / longitude | Geographic coordinates |
| timezone | IANA timezone identifier |
| isp | Internet Service Provider |
| org | Organisation name |
| as_number / as_name | Autonomous System details |
| is_tor | Whether the IP is a known Tor exit node |
| is_proxy | Whether the IP is a known proxy/VPN |
| is_datacenter | Whether the IP belongs to a datacentre |
| blacklists | Array of blacklist entries (source, category, listed_at) |
| threat_assessment.score | Overall threat score (0–100) |
| threat_assessment.level | Risk level: low, medium, high, critical |
| threat_assessment.reasons | Array of reasons contributing to the score |
| ai_agent_assessment.score | AI Agent Assessment score (0–100). Always present. |
| ai_agent_assessment.level | Confidence band: unlikely, possible, probable, confirmed |
| ai_agent_assessment.signals | Array of contributing signals; each has name, family, weight, observed_at and an optional redacted note |
| ai_agent_assessment.signals[].family | One of: prompt_injection, behavioural, payload, transport |
| ai_agent_assessment.methodology_version | Published methodology version used to compute this assessment |
ASN Lookup
Retrieve enrichment summary for an Autonomous System by AS number. Returns AS metadata, risk breakdown, blacklisted IP counts out of total IPs, and per-IP threat details.
/api/v1/lookup?asn={as_number}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| asn | string | Yes | AS number (e.g. "AS15169" or "15169") |
Example Request
Example Response
CIDR Lookup
Retrieve enrichment summary for an IPv4 CIDR block. Returns all known IPs within the range with threat and blacklist data. Prefix length must be between /8 and /32.
/api/v1/lookup?cidr={cidr_block}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| cidr | string | Yes | IPv4 CIDR block (e.g. "8.8.8.0/24") |
Example Request
Example Response
Bulk Lookup
Submit up to 100 IPs in a single call. Each public IP in the batch consumes one request from your hourly quota. RFC 1918 (private) addresses are returned without consuming quota.
/api/v1/bulk-lookup
Example Request
Teaser (no API key)
Unauthenticated evaluation endpoint with a tight per-source-IP rate limit of 10 requests/hour. Returns a trimmed enrichment payload — enough to evaluate the service, not enough to replace an authenticated integration. Paste a curl command into a chat channel to demo the API without anyone needing an account.
/api/v1/teaser?ip={address}
Example Request
Threat-Intel Feeds (STIX / TAXII / MISP)
The same indicators that power the blocklist are exposed over the wire protocols used by serious TIPs. All three feeds are anonymous and regenerated every 4 hours.
- STIX 2.1 bundle —
/downloads/blocklist-stix.json - TAXII 2.1 server — discovery at
/taxii2/; consumable by OpenCTI, MISP, Anomali and any other TIP that speaks TAXII. - MISP feed — manifest at
/downloads/misp/manifest.json; a MISP administrator can add this URL in three clicks.
Submit a Report
Contribute observed attackers back to ipinsights.io. Every adopter of one of our integration guides can opt into a small reciprocal upload script, turning their SIEM into a sensor. Submissions are weighted by the submitter's reputation, which evolves over time as reports are corroborated by other intelligence sources.
/api/v1/report
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| ip | string | Yes | Public IPv4 or IPv6 address of the observed attacker |
| categories | array | string | Yes | One to five category tags. May be a JSON array or a comma-separated string. |
| comment | string | No | Free-text context (≤ 1,024 chars). |
| source | string | No | Integration identifier — one of wazuh, graylog, splunk, sentinel, crowdsec, fail2ban, suricata, thehive, n8n, home_assistant, manual. |
Allowed Categories
ssh_bruteforce, rdp_bruteforce, web_bruteforce, web_attack, sql_injection, xss, port_scan, vulnerability_scan, exploit_attempt, credential_stuffing, phishing, spam, malware, ddos, botnet, c2, tor_abuse, open_proxy_abuse, other.
Example Request
Example Response (HTTP 201)
Notes on Data Quality
- Each report consumes one unit of your hourly
/api/v1/lookupquota. - Private / reserved IPs (RFC 1918, loopback, etc.) are rejected.
- Submitting the same IP repeatedly within 15 minutes from the same key is rate-limited at the application layer (HTTP 400).
- Submissions are weighted by submitter reputation (
0.10—2.00). New reporters start at1.00; reports corroborated by existing blacklist hits raise the score, reports invalidated by an admin lower it. - The unweighted contents of a single report are not sufficient on their own to add an IP to a blocklist — they feed into the aggregate threat assessment alongside our own sensor network and the 23+ threat-intel feeds we already cross-reference.
Error Codes
| Code | Meaning |
|---|---|
| 201 | Report created (POST /api/v1/report) |
| 400 | Invalid request (missing or malformed IP, ASN, or CIDR) |
| 401 | Missing or invalid API key |
| 422 | IP address is private or reserved |
| 429 | Rate limit exceeded |
| 500 | Internal server error |