RiskScore API

API reference

RiskScore HTTP endpoints on api.syndaq.com.

All RiskScore endpoints are served from https://api.syndaq.com/v1/riskscore/.

Authenticated requests require a valid RiskScore key. Lookup routes require your rs_sec_ secret key.

Endpoints overview

Method	Path	Auth	Purpose
GET	`/v1/riskscore/lookup`	Secret key	Lookup by `?ip=` query parameter
GET	`/v1/riskscore/lookup/{ip}`	Secret key	Lookup by IP in the URL path
GET	`/v1/riskscore/status`	Public or secret key	Plan limits and quota snapshot

Response headers

Successful and error responses may include:

Header	Description
`X-Request-Id`	Unique ID for support and log correlation
`X-RateLimit-Limit`	Plan requests per minute for this key
`X-RateLimit-Remaining`	Requests left in the current minute window
`X-RateLimit-Reset`	Unix timestamp when the minute window resets
`X-Quota-Limit`	Monthly quota for the subscription
`X-Quota-Remaining`	Lookups left this calendar month (UTC)
`X-Quota-Period`	Current quota month (`YYYY-MM`)
`Retry-After`	Seconds to wait after HTTP 429

GET /v1/riskscore/lookup

Returns risk intelligence for a single IP address.

Request

Pass the target IP using one of these forms:

GET /v1/riskscore/lookup/8.8.8.8
GET /v1/riskscore/lookup?ip=8.8.8.8

Both IPv4 and IPv6 are supported. IPv6 addresses in the path should be URL-encoded.

Headers:

Authorization: Bearer rs_sec_YOUR_SECRET_KEY

Success response (200)

{
  "success": true,
  "ip": "8.8.8.8",
  "cached": true,
  "provider": "findip",
  "fetched_at": "2026-06-22 12:00:00.000",
  "location": {
    "country": {
      "code": "US",
      "name": "United States"
    },
    "city": "Mountain View",
    "region": "California",
    "latitude": 37.386,
    "longitude": -122.084,
    "timezone": "America/Los_Angeles"
  },
  "network": {
    "isp": "Google LLC",
    "asn": 15169,
    "connection_type": "Corporate"
  },
  "intelligence": {
    "verdict": "anonymous_traffic",
    "description": "VPN or proxy exit detected",
    "risk": {
      "score": 15,
      "level": "low"
    },
    "threat": {
      "score": 50,
      "level": "medium"
    },
    "flags": {
      "is_anonymous": true,
      "is_proxy": false,
      "is_vpn": true,
      "is_tor": false,
      "is_relay": false,
      "is_malicious": false,
      "is_hosting": false,
      "is_network_service": true
    },
    "anonymous_confidence": 85,
    "tags": ["vpn"],
    "categories": ["anonymizer"]
  },
  "is_eu": false,
  "request_id": "a1b2c3d4e5f6789012345678901234ab"
}

Response fields

Field	Type	Description
`cached`	boolean	`true` when served from cache or local database
`location`	object	Country, city, region, coordinates, timezone
`network`	object	ISP, ASN, and connection type
`intelligence.verdict`	string	Overall assessment code
`intelligence.description`	string	Human-readable verdict summary
`intelligence.risk`	object	Overall risk score and level
`intelligence.threat`	object	Threat score and level
`intelligence.flags`	object	Boolean anonymity and abuse indicators
`intelligence.anonymous_confidence`	integer	Confidence for anonymity detection (0-100)
`intelligence.tags`	array	Provider tag strings
`intelligence.categories`	array	Provider category strings
`is_eu`	boolean	Whether the country is in the European Union

See the Risk intelligence guide for how to act on verdicts and scores.

GET /v1/riskscore/status

Returns key status, plan limits, and quota usage without performing a lookup.

Request

GET /v1/riskscore/status
Authorization: Bearer rs_sec_YOUR_SECRET_KEY

The public key (rs_pub_) is accepted on this route.

Success response (200)

{
  "success": true,
  "status": "active",
  "product": "riskscore",
  "plan": "starter",
  "rate_limit_per_minute": 120,
  "monthly_quota": 10000,
  "quota_unlimited": false,
  "quota_remaining": 9842,
  "quota_period": "2026-06",
  "database_records": 850000
}

Errors

Failed requests return JSON with success: false, error, error_code, and usually request_id.

HTTP	error_code	Typical cause
400	`invalid_ip`	Missing or malformed IP address
401	`missing_credentials`	No API key provided
401	`invalid_api_key`	Unknown, inactive, or revoked key
401	`wrong_key_type`	Public key used on a lookup endpoint
403	`ip_not_allowed`	Caller IP not on the key allowlist
404	`ip_not_found`	Upstream could not resolve the address
422	`ip_not_routable`	Private, reserved, or non-routable IP
429	`rate_limit_exceeded`	Per-minute limit exceeded
429	`quota_exceeded`	Monthly quota exhausted
502	`lookup_failed`	Temporary upstream error
503	`upstream_unconfigured`	RiskScore upstream not configured on server
500	`internal_error`	Unexpected server error

Handle non-200 responses in your application and retry transient errors with exponential backoff.