Core endpoints

Authentication

Send your API key in X-API-Key (e.g. prdx_...).

POST /api/v1/check/ip

curl -sS https://predax.io/api/v1/check/ip \
  -H "X-API-Key: prdx_..." \
  -H "Content-Type: application/json" \
  -d '{"ip":"8.8.8.8"}'

Optional enrichment: send user_id, context, signals, and fingerprint to enable best-effort residential proxy suspicion.

Request body (optional fields)

{
  "ip": "1.2.3.4",
  "user_id": "user_123",
  "context": { "user_timezone": "Europe/Dublin" },
  "signals": { "distinct_user_agents_24h": 7, "requests_24h": 120 },
  "fingerprint": {
    "timezone": "Europe/Dublin",
    "languages": ["en-IE", "en"],
    "webrtc_local_ip": "192.168.1.100"
  }
}

Response shape (single IP)

The response is a JSON object. All nested objects (classification, network, location) are always present; cloud, crawler, history, and meta are optional and only included when relevant.

{
  "ip": "8.8.8.8",
  "version": 4,
  "classification": {
    "risk_score": 15,
    "risk_level": "low",
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_hosting": false,
    "is_crawler": false,
    "is_private_relay": false,
    "is_warp": false,
    "flags": ["datacenter"],
    "confidence": { "datacenter": 0.95, "overall": 0.95 },
    "reasons": [
      { "flag": "datacenter", "source": "datacenter_feed" }
    ]
  },
  "network": {
    "asn": 15169,
    "as_name": "GOOGLE",
    "cidr": "8.8.8.0/24",
    "network_type": "hosting",
    "ptr": "dns.google"
  },
  "location": {
    "country_code": "US",
    "country_name": "United States",
    "city": "Mountain View",
    "latitude": 37.4056,
    "longitude": -122.0775,
    "timezone": "America/Los_Angeles"
  },
  "cloud": {
    "provider": "google",
    "service": "Public DNS",
    "cidr": "8.8.8.0/24"
  },
  "history": {
    "first_seen": "2026-01-10T12:34:56",
    "last_seen": "2026-05-04T09:00:00",
    "times_seen": 50
  },
  "meta": {
    "request_id": "req_abc123",
    "cached": true,
    "cache_ttl_seconds": 3600,
    "processed_ms": 4.2
  }
}

Top-level boolean flags (is_vpn, is_tor, etc.) live under classification — the response has no flat top-level flags. Read result.classification.is_vpn, not result.is_vpn.

POST /api/v1/check/ip/bulk

Max 100 IPs per request.

curl -sS https://predax.io/api/v1/check/ip/bulk \
  -H "X-API-Key: prdx_..." \
  -H "Content-Type: application/json" \
  -d '{"ips":["8.8.8.8","1.1.1.1"]}'

The bulk response is a top-level JSON array, one element per requested IP, each with the same shape as the single-IP response above:

[
  { "ip": "8.8.8.8", "version": 4, "classification": { "risk_score": 15, ... }, "network": { ... }, "location": { ... } },
  { "ip": "1.1.1.1", "version": 4, "classification": { "risk_score": 10, ... }, "network": { ... }, "location": { ... } }
]

Bulk requests consume N units where N = ips.length.

GET /api/v1/billing/usage

Returns monthly usage summary plus a daily quota object.

curl -sS https://predax.io/api/v1/billing/usage \
  -H "X-API-Key: prdx_..."

POST /api/v1/validate/email

Email syntax + disposable/free-provider checks (MX optional).

curl -sS https://predax.io/api/v1/validate/email \
  -H "X-API-Key: prdx_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","check_mx":false}'

POST /api/v1/validate/phone

E.164 validation (best-effort).

curl -sS https://predax.io/api/v1/validate/phone \
  -H "X-API-Key: prdx_..." \
  -H "Content-Type: application/json" \
  -d '{"phone":"+14155552671"}'

Headers you should read

• Request tracing: X-Request-ID
• Daily quota: X-Quota-Limit-Day, X-Quota-Used-Today, X-Quota-Remaining-Today, X-Quota-Reset-Daily
• Monthly quota: X-Quota-Limit-Month, X-Quota-Used-Month, X-Quota-Remaining-Month, X-Quota-Month
• Per-second: X-RateLimit-Limit-Per-Second, X-RateLimit-Remaining-This-Second

Errors and retries

• 401: missing/invalid API key
• 402: daily or monthly quota exceeded (quota headers are still returned)
• 429: per-second rate limit exceeded (retry with backoff)
• 422: invalid request body (schema validation)

For reliability, use short timeouts (1–3s), retry 429/5xx with exponential backoff, and log X-Request-ID.

Public endpoints (no auth)