What You Will Achieve
By the end of this playbook you will have:
- A decision matrix for
GET /check/reputationvsGET /check - Copy-paste curl for both routes with the same auth header
- Guidance on
GET /check/whoisandGET /check/locationwhen you need a single data slice - A Python helper that tries reputation first and escalates to full check on suspicion
Prerequisites
| Requirement | Details |
|---|---|
| API key + secret | X-API-KEY = Base64(apiKey:apiSecret) |
| Understanding of enrichment | Full /check supports the enrichment query param per OpenAPI (basic, standard or full); deeper tiers cost more work server-side |
Reference: Lookup API and OpenAPI.
When to use each endpoint
| Goal | Endpoint | Why |
|---|---|---|
| High-volume scoring, dashboards, first-pass allow/deny | GET /check/reputation?query= |
Returns aggregated reputation counts; narrower payload than full analysis |
| Incident triage, hunting, executive summary | GET /check?query=&enrichment=standard (or full) |
Risk score, classification, confidence, geo, and richer context |
| Registrar / ownership questions only | GET /check/whois?query= |
Avoid pulling the full graph when WHOIS is enough |
| Geo-IP or ASN context only | GET /check/location?query= |
Lighter than full check when location is the only signal |
Step 1: Same auth, two requests
bash
export B64=$(printf '%s' "${API_KEY}:${API_SECRET}" | base64 | tr -d '\n')
Q="example.com"
# Reputation-only
curl -sS "https://api.ismalicious.com/check/reputation?query=${Q}" \
-H "X-API-KEY: ${B64}" | jq .
# Full analysis (example: standard enrichment)
curl -sS "https://api.ismalicious.com/check?query=${Q}&enrichment=standard" \
-H "X-API-KEY: ${B64}" | jq .
Compare response size and latency in your environment to calibrate pipelines.
Step 2: Escalation pattern in Python
python
import base64
import os
import urllib.parse
import urllib.request
API_KEY = os.environ["ISMALICIOUS_API_KEY"]
API_SECRET = os.environ["ISMALICIOUS_API_SECRET"]
def hdr():
return {
"X-API-KEY": base64.b64encode(f"{API_KEY}:{API_SECRET}".encode()).decode()
}
def get_json(path: str, params: dict):
q = urllib.parse.urlencode(params)
url = f"https://api.ismalicious.com{path}?{q}"
req = urllib.request.Request(url, headers=hdr())
with urllib.request.urlopen(req, timeout=30) as resp:
import json
return json.loads(resp.read().decode())
def analyze(entity: str):
rep = get_json("/check/reputation", {"query": entity})
r = rep.get("reputation") or {}
malicious = int(r.get("malicious") or 0)
suspicious = int(r.get("suspicious") or 0)
if malicious + suspicious >= 3:
return get_json("/check", {"query": entity, "enrichment": "standard"})
return rep
if __name__ == "__main__":
print(analyze("8.8.8.8"))
Tune the threshold to match your false-positive tolerance. The idea is cheap wide net, expensive deep dive.
Step 3: Batching many entities
For lists, prefer POST /bulk/check (see Bulk IOC triage playbook) instead of parallel hammering /check/reputation.
Related reading
- Bulk API — batch domains, IPs, and URLs.
- API rate limits — burst and monthly quotas.