API Documentation
RESTful JSON API for IP address, ASN, and network intelligence.
Quick Start
curl https://api.ipctl.io/v1/ip/1.1.1.1
# Response:
{
"data": {
"ip": "1.1.1.1",
"ip_version": 4,
"reverse_dns": "one.one.one.one",
"is_bogon": false,
"asn": { "asn": 13335, "name": "CLOUDFLARENET", ... },
"geo": { "country_code": "US", "country_name": "United States", ... },
"threat_score": 0,
"tags": []
}
}
# Threat intelligence (separate endpoint, 1 credit):
curl https://api.ipctl.io/v1/intel/1.1.1.1
# Response:
{
"data": {
"score": 60,
"intel": [
{ "tag": "tor-node", "severity": "medium" },
{ "tag": "c2", "severity": "critical" }
]
}
}curl https://api.ipctl.io/v1/ip/1.1.1.1 \ -H "X-API-Key: nq_your_key_here" # Or via Bearer token: curl https://api.ipctl.io/v1/ip/1.1.1.1 \ -H "Authorization: Bearer nq_your_key_here"
Authentication
API keys start with nq_. Pass them via X-API-Key header or Authorization: Bearer nq_xxx. An invalid, revoked or expired key is rejected with 401 (INVALID_API_KEY, API_KEY_EXPIRED); the request does not fall back to anonymous access.
Credits: with an API key, IP, ASN, ASN risk, prefix and intel lookups cost 1 credit, bulk lookups 1 credit per unique IP; all other endpoints are free. Requests without a key use no credits, only the anonymous rate limits.
Rate-limited endpoints (all except /v1/health and /v1/mcp) return these headers; the credit headers only on credit-consuming endpoints called with a key. Example for a free API key:
X-RateLimit-Limit: 30 X-RateLimit-Remaining: 29 X-RateLimit-Reset: <unix timestamp at which the current minute window ends> X-RateLimit-Limit-Day: 1000 X-RateLimit-Remaining-Day: 999 X-RateLimit-Credits-Remaining: 9999 X-RateLimit-Credits-Reset: <start of next calendar month, ISO 8601>
A 429 response carries Retry-After with the seconds until the window ends.
Endpoints
IP address lookup: geolocation, ASN, BGP routes, RPKI status, and an overall threat score.
curl https://api.ipctl.io/v1/ip/1.1.1.1
Threat intelligence for an IP: overall score and an array of individual findings (tag, severity).
curl https://api.ipctl.io/v1/intel/1.1.1.1
ASN information: registry details, registered prefixes (first 500), routing statistics and ASPA status. Add ?format=text for a plain-text summary.
curl https://api.ipctl.io/v1/asn/13335
Prefixes the ASN announces in BGP, with RPKI status. Paginated: a response holds at most ?limit= prefixes (default 100, max 1000); pagination.total is the full count, so repeat with ?offset= increased by the limit until it reaches the total. (The prefixes field of /v1/asn/{asn} lists registered RIR prefixes, capped at 500.)
curl "https://api.ipctl.io/v1/asn/13335/prefixes?limit=1000&offset=0" # next page: ...&offset=1000, until offset >= pagination.total
ASPA: upstream providers the ASN has authorized in RPKI. Empty array when the ASN has no ASPA object. /v1/asn/{asn}/downstreams lists the ASNs that name it as a provider.
curl https://api.ipctl.io/v1/asn/3320/upstreams
Routing-risk score of an ASN (0-100, higher is riskier) with level and reasons: RPKI ROA and IRR route object coverage of its announced prefixes, IRR origin mismatches, hijack signals and upstream diversity. Recomputed daily; 404 when the ASN announces no prefixes.
curl https://api.ipctl.io/v1/asn/13335/risk
Prefix information including more-specifics, BGP routes, RPKI/IRR status and RIR allocation data. Add ?format=text for a plain-text summary.
curl "https://api.ipctl.io/v1/prefix/1.1.1.0/24"
WHOIS-style registration data for an IP: network allocation, RIR, ASN, organization, abuse contact, and geolocation.
curl https://api.ipctl.io/v1/whois/1.1.1.1
Find ASNs and prefixes by organisation or network name, ASN, IP address or prefix (2-200 characters, up to 20 results). An IP or prefix returns the covering prefixes. Pass ?q=cloudflare
curl "https://api.ipctl.io/v1/search?q=cloudflare"
Returns the full IP info for the caller's own IP address.
curl https://api.ipctl.io/v1/me/ip
Bulk IP lookup for up to 1,000 IPs in a single request (the limit depends on your plan). Returns geolocation, ASN, and basic threat score per IP. Requires an API key on a paid plan.
curl -X POST https://api.ipctl.io/v1/bulk \
-H "Authorization: Bearer nq_xxx" \
-H "Content-Type: application/json" \
-d '{"ips":["1.1.1.1","8.8.8.8"]}'API Reference
The full API is described in an OpenAPI 3.1 specification. Use it to generate client libraries, import into Postman, or browse the interactive reference.
MCP Server for AI Agents
AI assistants that support the Model Context Protocol (Claude Code, Cursor, VS Code and others) can use ipctl directly: IP reputation, IP/ASN/prefix lookups, ASN routing-risk scores, RPKI, ASPA and WHOIS as read-only tools. Connect to https://api.ipctl.io/v1/mcp with your API key; each tool call uses the credits and rate limits of the REST request(s) it makes (aspa_lookup makes two).
Pricing
All plans include full API access. Upgrade or downgrade anytime.
- All lookup endpoints
- IP, ASN, prefix lookups
- Basic threat score on /ip
- BGP monitoring for 2 prefixes
- Everything in Free
- Bulk lookups (up to 100 IPs)
- AI service detection on /ip
- BGP monitoring for 10 prefixes
- Email support
- Everything in Starter
- Bulk lookups (up to 1,000 IPs)
- BGP monitoring for 50 prefixes
- Custom network flags
- SLA 99.9%
- Everything in Pro
- 2.5M requests/month
- BGP monitoring for 250 prefixes
- Fraud detection use case
- Priority support
- Custom credit allowance
- BGP monitoring for 1,000+ prefixes
- Dedicated infrastructure
- Custom integrations
- Priority SLA
BGP monitoring emails you when a monitored prefix is hijacked (new origin AS or rogue more-specific), stops being announced, or turns RPKI invalid.
All prices include applicable taxes (VAT/GST).