senapati
Documentation index
Getting started

Quickstart

Zero to a scored IP in about two minutes: one account, one key, one request. The account and the key come from the dashboard; after that, everything is an API call.

1. Create an account

Create a free account. New accounts start on the Free plan with 100 credits a month and two API keys.

2. Create an API key

Dashboard → API keys → Create. Name the key after the integration that will use it. The full key is shown once; afterwards you only ever see its prefix.

3. Make your first request

Send the key in the X-API-Key header. This checks an IP against every enabled blacklist engine, enriches it with geolocation, ASN, provider-range and anonymity data, and returns a 0–100 risk score. It costs one credit.

curl -X POST "https://api.senapati.io/api/check-ip" \
  -H "X-API-Key: $SENAPATI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"54.239.28.85"}'

4. Read the response

response: 200 OKIPReputationResponse
{
  "request_id": "req_8f2c1a7e",
  "timestamp": "2026-08-27T11:59:46.179439+00:00",
  "data": {
    "ip": "54.239.28.85",
    "version": "IPv4",
    "blacklists": {
      "engines": {
        "0": {
          "name": "0spam",
          "detected": false,
          "reference": "https://0spam.org/",
          "elapsed_ms": 15
        },
        "5": {
          "name": "Backscatterer",
          "detected": false,
          "reference": "https://www.backscatterer.org/",
          "elapsed_ms": 1181
        },
        "6": {
          "name": "Barracuda_Reputation_BL",
          "detected": false,
          "reference": "https://barracudacentral.org/lookups",
          "elapsed_ms": 7
        },
        "…": "60 more engines omitted from this example"
      },
      "detections": 0,
      "engines_count": 63,
      "detection_rate": "0%",
      "scan_time_ms": 2002
    },
    "information": {
      "reverse_dns": null,
      "is_eu": false,
      "continent_code": "NA",
      "continent_name": "North America",
      "country_code": "US",
      "country_name": "United States",
      "currency": "USD",
      "currency_name": "US Dollar",
      "currency_name_plural": "US dollars",
      "currency_symbol": "$",
      "currency_symbol_native": "$",
      "calling_code": "",
      "emoji_flag": "🇺🇸",
      "emoji_flag_unicode": "U+1F1FA U+1F1F8",
      "region_name": "Virginia",
      "city_name": "Ashburn",
      "latitude": 39.0469,
      "longitude": -77.4903,
      "isp": "Amazon.com, Inc.",
      "asn": "AS16509",
      "is_bogon": false,
      "is_spamhaus_drop": false,
      "is_fake_bot": false,
      "is_google_bot": false,
      "is_search_engine_bot": false,
      "related_service_name": "",
      "related_service_domain": "",
      "related_service_type": "",
      "is_major_provider_spf_ip": false,
      "is_public_dns": false,
      "cloud_provider": "Amazon AWS",
      "cloud_provider_domain": "aws.amazon.com",
      "aws_service": "AMAZON",
      "is_google_service": false,
      "edge_service": "",
      "edge_service_domain": "",
      "is_satellite": false,
      "is_hosting": false
    },
    "asn": {
      "asn": "AS16509",
      "asname": "Amazon.com, Inc.",
      "route": "",
      "status": "active",
      "org": "Amazon.com, Inc.",
      "country_code": "",
      "created": "",
      "days_since_created": 0,
      "updated": "",
      "days_since_updated": 0,
      "address": "",
      "abuse_email": "",
      "domain": "",
      "total_ipv4_prefixes": 0,
      "total_ipv4_ips": 0,
      "total_ipv6_prefixes": 0,
      "type": "hosting",
      "rir": ""
    },
    "anonymity": {
      "is_proxy": false,
      "is_webproxy": false,
      "is_residential_proxy": false,
      "is_vpn": false,
      "is_hosting": true,
      "is_relay": false,
      "is_tor": false
    },
    "risk_score": {
      "result": 0
    },
    "elapsed_ms": 8,
    "sia_enrichment": null
  }
}

Everything sits under data. The parts you will use first:

  • risk_score.result: 0 (clean) to 100 (dangerous). One blacklist hit is 40, two are 70, three or more saturate at 100; Tor exits are always 100.
  • blacklists.detections / engines_count: how many engines flagged the IP out of how many ran, with the per-engine verdicts in blacklists.engines.
  • information: geolocation, ISP, and provider facts such as cloud_provider, aws_service, is_google_bot, is_spamhaus_drop.
  • anonymity: is_tor, is_vpn, is_relay (Apple Private Relay), is_hosting.

The engines map is abbreviated in the example above; a real response lists every engine that ran.

Next

  1. Handle failures the same way everywhere: the error envelope is identical on every route.
  2. Check what each call costs and how rate limits work in Credits & rate limits.
  3. Batch up to 100 lookups per request with the bulk endpoints.