REST API Reference

The IPScope REST API (@ipscope/api) is a low-latency NestJS + Fastify service served over HTTPS (HTTP/2 and HTTP/3) from https://api.ipscope.io. Lookups resolve in sub-millisecond memory against an atomic Radix/LPM routing snapshot, with automatic live BGP, RIPEstat, and RDAP #geofeed enrichment on cache misses.

# Quick request & response explorer

Select your preferred language tab below (curl, Python, Node.js, Go, Rust, Java, .NET, Ruby, PHP). Your selection is automatically remembered across every page in the documentation.

curl -sS "https://api.ipscope.io/v1/ip/198.51.100.7" \
  -H "Authorization: Bearer $IPSCOPE_KEY"

{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94,
    "subdivision": "Virginia",
    "city": "Ashburn",
    "postal_code": "20147",
    "latitude": 39.0438,
    "longitude": -77.4874,
    "accuracy_radius_km": 10,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 64501,
    "organization": "Example Cloud LLC"
  },
  "connection": {
    "connection_type": "hosting",
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_business": false
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  },
  "security_extensions": {
    "abuse_velocity_score": 18,
    "is_known_scanner": false,
    "observation_recency_hours": 12,
    "anonymizer_reason": "vpn_handshake_confirmed",
    "threat_level": "medium",
    "abuse_velocity": "low",
    "confidence": 0.96
  },
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "updated_at": "2026-10-27T00:00:00Z"
}

# Service endpoints

All endpoints are versioned under /v1 and grouped into two controllers: Lookup & Telemetry (LookupController) and MMDB & Artifact Distribution (MmdbController).

# Lookup & Telemetry (`LookupController`)

# MMDB & Artifact Distribution (`MmdbController`)

# Authentication & API key scopes

Authenticated endpoints are protected by ApiKeyGuard. Pass your API key in either the Authorization: Bearer <key> header or the x-api-key: <key> header. Keys are hashed with SHA-256 and verified in sub-millisecond memory against the hot key cache.

curl -sS "https://api.ipscope.io/v1/ip/198.51.100.7" \
  -H "Authorization: Bearer ips_live_••••••••"

Every API key is provisioned with explicit permission scopes (ApiKeyScope) and licensed field families (licensedFamilies). If a key lacks the required scope for a route, the API returns 403 Forbidden.

# Per-user rate limiting & headers

Rate limits are enforced per user account (rl:user:<userId>), shared across all active API keys owned by that user. Creating multiple keys for microservice isolation never multiplies burst limits or bypasses account-level rate governance.

# Prepaid credit reservation & metering

Metered endpoints (GET /v1/ip/:ip = 1 unit, POST /v1/ip/batch = ips.length units) debit from a low-latency Valkey credit reservation chunk backed by our PostgreSQL double-entry ledger (100 micro-USD per lookup = $0.10 per 1,000 lookups).

• Atomic pre-validation: On POST /v1/ip/batch, every IP in ips[] is validated *before* credits are debited. Malformed requests (400 Bad Request) never consume credits.
• Explicit 402 Payment Required: When your monthly plan allowance and prepaid wallet reservation are exhausted, metered endpoints return 402 Payment Required rather than silently accruing surprise post-paid overage bills.
• Unmetered operational endpoints: GET /v1/status, GET /v1/ip/me, GET /v1/metadata/datasets, and POST /v1/feedback do not debit lookup credits.

# Explore endpoint specifications