API v1
IP Cleanliness API
Use one endpoint for IP cleanliness scores, network type, proxy, VPN, Tor, location, and ASN. Web checks, batch jobs, and the API share the same 16-source scoring engine.
Request
| Field | Type | Required | Description |
|---|---|---|---|
| ip | string | Yes | Public IPv4 or IPv6 address, up to 64 characters |
curl -X POST https://iprisk.top/v1/check -H "Authorization: Bearer ipr_live_xxx" -H "Content-Type: application/json" -d '{"ip":"1.1.1.1"}'const response = await fetch('https://iprisk.top/v1/check', {
method: 'POST',
headers: { Authorization: 'Bearer ipr_live_xxx', 'Content-Type': 'application/json' },
body: JSON.stringify({ ip: '1.1.1.1' })
});
const result = await response.json();import requests
response = requests.post(
'https://iprisk.top/v1/check',
headers={'Authorization': 'Bearer ipr_live_xxx'},
json={'ip': '1.1.1.1'},
timeout=60,
)
result = response.json()<?php
$ch = curl_init('https://iprisk.top/v1/check');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ipr_live_xxx', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['ip' => '1.1.1.1']),
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);requestBody := strings.NewReader(`{"ip":"1.1.1.1"}`)
req, _ := http.NewRequest("POST", "https://iprisk.top/v1/check", requestBody)
req.Header.Set("Authorization", "Bearer ipr_live_xxx")
req.Header.Set("Content-Type", "application/json")
response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)Success response
{
"success": true,
"request_id": "7f3e8d21-...",
"cached": false,
"credits_remaining": 9999,
"billing": {
"charged": true,
"credits": 1,
"success_sources": 16,
"minimum_sources": 12,
"missing_coverage_groups": []
},
"data": {
"ip": "1.1.1.1",
"score": 45,
"cleanliness_level": "low",
"ip_type": "datacenter",
"proxy": false,
"vpn": false,
"tor": false,
"hosting": true,
"country": "Australia",
"country_code": "AU",
"city": "Sydney",
"asn": "AS13335",
"organization": "Cloudflare, Inc.",
"success_sources": 16,
"checked_at": "2026-09-20T12:00:00.000Z"
}
}
Response fields
| Field | Type | Description |
|---|---|---|
| ip | string | Normalized public IPv4 / IPv6 address |
| score | number | 0–100 cleanliness score; higher is cleaner |
| cleanliness_level | string | excellent / good / fair / low / very_low / poor |
| ip_type | string | Network type, such as residential, mobile, or datacenter |
| proxy / vpn / tor | boolean | Proxy, VPN, and Tor detection results |
| hosting | boolean | Whether the address belongs to hosting or a datacenter |
| country / country_code / city | string | null | Consensus geolocation result |
| asn / organization | string | null | Autonomous system number and network organization |
| success_sources | number | Successful source count, up to 16 |
| checked_at | string | ISO 8601 completion timestamp |
| billing.charged | boolean | Whether this request was actually charged |
| billing.credits | number | Credits charged for this request: always 0 or 1 |
During the compatibility period, risk_level remains for older clients. New integrations should use cleanliness_level.
Billing and result quality
Each request reserves one credit. It is charged only when at least 12 sources succeed and critical coverage for network identity, proxy/VPN, routing, and threat intelligence is complete. Failed or incomplete checks are automatically refunded while any usable result is still returned. Cache hits count as valid queries.
Scores and weights are identical to the web check. Raw third-party payloads are not exposed by the API.
Status codes and handling
| HTTP | code | Meaning | Action |
|---|---|---|---|
| 400 | invalid_ip / unsupported_ip | Invalid IP format or non-public address | Fix the request; do not retry the same value |
| 401 | invalid_api_key | Missing or invalid API key | Check the Bearer key |
| 402 | insufficient_credits | Insufficient credits | Add credits or upgrade the plan |
| 409 | query_in_progress | The same IP is already being checked | Retry shortly |
| 429 | rate_limited | Plan rate limit exceeded | Slow down and back off |
| 503 | engine_busy / backend_unavailable | Service temporarily busy or recovering | Retry with exponential backoff |
Usage conventions
- X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset describe the active window. On 429, retry after the interval in Retry-After.
- Use HTTPS and never expose API keys in frontend code, public repositories, or logs.
- Use request_id for troubleshooting. Share it with support, never the API key.
- CORS is supported, but production integrations should keep and use the API key on your own server.