POST /api/check

Request

Method: POST
Path: /api/check
Content-Type: application/json

Body parameters

url

string

required

The URL to analyze. Must be a string. The heuristics checker normalizes URLs, so the http:// prefix is optional — bare hostnames and paths are accepted.

Example requests

curl -X POST http://localhost:4000/api/check \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response

On success the API returns 200 OK with a ScanResult object.

Response fields

url

string

required

The original URL that was submitted for analysis.

score

number

required

Aggregate threat score from 0 to 100 (capped at 100). Higher values indicate greater risk.

verdict

string

required

Threat verdict based on the score: "safe" if score < 40, "suspicious" if 40–69, "phishing" if ≥ 70.

reasons

string[]

required

Array of human-readable explanations for the score. Empty for clean URLs.

executionTimeMs

object

Per-checker execution time in milliseconds. Keys correspond to checker names. See ScanResult schema for the full list of keys.

Example responses

Safe
Suspicious
Phishing

{
  "url": "https://example.com",
  "score": 8,
  "verdict": "safe",
  "reasons": [],
  "executionTimeMs": {
    "heuristics": 120,
    "openphish": 45,
    "google_safe_browsing": 230,
    "urlhaus": 12,
    "phishtank": 18,
    "phishstats": 38
  }
}

{
  "url": "http://login-verify-account.support-center.net/secure",
  "score": 53,
  "verdict": "suspicious",
  "reasons": [
    "URL is not HTTPS",
    "Contains suspicious keywords",
    "Hyphens in domain",
    "Domain is recently created (<90 days)"
  ],
  "executionTimeMs": {
    "heuristics": 985,
    "openphish": 41,
    "google_safe_browsing": 218,
    "urlhaus": 10,
    "phishtank": 21,
    "phishstats": 33
  }
}

{
  "url": "http://secure-login.account-verify.xyz/update@support",
  "score": 100,
  "verdict": "phishing",
  "reasons": [
    "Contains '@' (phishing trick)",
    "Contains suspicious keywords",
    "Hyphens in domain",
    "URL is not HTTPS",
    "DNS failed or private network"
  ],
  "executionTimeMs": {
    "heuristics": 312,
    "openphish": 9,
    "google_safe_browsing": 198,
    "urlhaus": 7,
    "phishtank": 11,
    "phishstats": 14
  }
}

Error responses

Status	Condition	Response body
`400 Bad Request`	`url` field is missing or not a string	`{"error": "Missing 'url' in body"}`
`429 Too Many Requests`	Rate limit exceeded	`{"error": "Too many requests from this IP, please try again later.", "limit": 100, "current": <number>}`
`500 Internal Server Error`	Unexpected error during analysis	`{"error": "Server error", "detail": "<error string>"}`

See Error codes for full details.

Endpoints

Response Types

Request

Body parameters

Example requests

Response

Response fields

Example responses

Error responses

Build docs developers (and LLMs) love

Endpoints

Response Types

​Request

​Body parameters

​Example requests

​Response

​Response fields

​Example responses

​Error responses

Build docs developers (and LLMs) love

Request

Body parameters

Example requests

Response

Response fields

Example responses

Error responses