API Documentation

The Overisk AI API returns a 0–100 risk score for any domain, email address, or IP — in real time. Use it to block fraud at signup, filter spam, or enrich your threat intel pipeline.

Base URL https://overisk.ai

Authentication

Pass your API key in the x-api-key request header. You receive your key by email after subscribing to Pro.

http

POST /risk-score
x-api-key: your_api_key_here
Content-Type: application/json

ℹ️ No key? You can call /risk-score without authentication. You get 3 free checks per day, rate-limited by IP address.

Base URL

All endpoints are relative to:

https://overisk.ai

All requests must use HTTPS. HTTP requests will be redirected.

Error handling

Errors return a standard JSON body with a detail field.

Status	Meaning
400	Bad request — invalid input
401	Invalid or missing API key
403	Forbidden — admin action without admin key
429	Plan limit exceeded for this billing period
500	Internal server error

json

{
  "detail": "Invalid API key"
}

Risk score

POST /risk-score

Returns a 0–100 risk score and signal breakdown for a domain, email address, or IP.

Request body

Field	Type	Description
typerequired	string	`"domain"`, `"email"`, or `"ip"`
valuerequired	string	The entity to score, e.g. `"example.com"`

Response fields

entityThe normalised entity that was scored

risk_scoreInteger 0–100. Higher = riskier

severity"low" · "medium" · "high"

signalsArray of strings describing detected risk factors

summaryShort human-readable description

usage (Pro)Object: requests_used, remaining_requests, plan

free_checks_remainingOnly on unauthenticated calls — how many anonymous checks remain today

Usage

GET /usage

Returns your current quota usage and when it resets. Requires an API key.

Response fields

plan"free" or "pro"

requests_usedRequests consumed in the current period

remaining_requestsRequests left before hitting the plan limit

reset_atISO 8601 timestamp when the counter resets

Subscribe

POST /subscribe

Creates a Stripe Checkout session for upgrading to Pro. Returns a checkout_url — redirect the user there to complete payment.

⚠️ This endpoint requires an existing free API key in the x-api-key header. Contact us if you need a key.

Response

checkout_urlStripe-hosted checkout page. Redirect the user here.

Health check

GET /health

Returns {"status": "ok"} when the service is running. Used by uptime monitors.

Examples — curl

Unauthenticated domain check (free)

bash

curl -X POST https://overisk.ai/risk-score \
  -H "Content-Type: application/json" \
  -d '{"type": "domain", "value": "suspicious-site.ru"}'

Authenticated email check (Pro)

bash

curl -X POST https://overisk.ai/risk-score \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{"type": "email", "value": "user@tempmail.com"}'

Check an IP address

bash

curl -X POST https://overisk.ai/risk-score \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{"type": "ip", "value": "185.220.101.1"}'

Check your quota

bash

curl https://overisk.ai/usage \
  -H "x-api-key: your_api_key_here"

Examples — Python

python

import requests

API_KEY = "your_api_key_here"
BASE    = "https://overisk.ai"

def check_risk(entity_type: str, value: str) -> dict:
    resp = requests.post(
        f"{BASE}/risk-score",
        headers={
            "x-api-key": API_KEY,
            "Content-Type": "application/json",
        },
        json={"type": entity_type, "value": value},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

# Example usage
result = check_risk("domain", "suspicious-site.ru")
print(result["risk_score"])   # e.g. 78
print(result["severity"])     # "high"
print(result["signals"])      # ["newly_registered", "suspicious_tld", ...]

# Block high-risk signups
if result["risk_score"] >= 70:
    raise ValueError("High-risk entity rejected")

Examples — Node.js

javascript

const API_KEY = "your_api_key_here";
const BASE    = "https://overisk.ai";

async function checkRisk(type, value) {
  const res = await fetch(`${BASE}/risk-score`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
    },
    body: JSON.stringify({ type, value }),
  });

  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

// Block high-risk email at signup
const result = await checkRisk("email", "user@tempmail.com");
if (result.risk_score >= 70) {
  throw new Error("Registration blocked: high-risk email");
}

Response format

Pro API key response

json

{
  "entity":     "suspicious-site.ru",
  "risk_score": 78,
  "severity":   "high",
  "signals": [
    "newly_registered",
    "suspicious_tld",
    "privacy_protected_whois"
  ],
  "summary": "Auto-generated risk analysis",
  "usage": {
    "plan":               "pro",
    "requests_used":      42,
    "remaining_requests": 9958
  }
}

Unauthenticated response

json

{
  "entity":     "suspicious-site.ru",
  "risk_score": 78,
  "severity":   "high",
  "signals": ["newly_registered", "suspicious_tld"],
  "summary":    "Auto-generated risk analysis",
  "free_checks_remaining": 2
}

Free limit reached

json

{
  "error":       "free_limit_reached",
  "message":     "You've used your 3 free checks. Upgrade to Pro for 10,000 requests/month.",
  "upgrade_url": "https://overisk.ai/#pricing"
}

Usage endpoint response

json

{
  "plan":               "pro",
  "requests_used":      42,
  "remaining_requests": 9958,
  "reset_at":           "2026-05-26T14:30:00"
}