Quickstart
Make your first scan in under 60 seconds. Get your API key from the dashboard after subscribing to any API plan.
curl -X POST https://scamdefender.ai/api/v1/scan \
-H "Content-Type: application/json" \
-H "x-api-key: sd_live_your_key_here" \
-d '{"type": "url", "content": "https://suspicious-site.com"}'Authentication
All API requests require an API key passed in the x-api-key header. Keys take the form sd_live_... and are generated from your dashboard.
Header
x-api-key: sd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Security note: Keep your API key secret. Never expose it in client-side code or commit it to version control. Use environment variables.
Endpoint
The API currently exposes a single unified scan endpoint.
POST
/api/v1/scanScan a URL, email address, or text message for scam indicators. Returns a verdict, confidence score, and actionable evidence.
Request body
Send a JSON body with two required fields:
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | required | One of: url, email, text |
| content | string | required | The URL, email address, or message text to scan. Max 10,000 characters. |
URL scan
{
"type": "url",
"content": "https://suspicious-bank.com/verify"
}Email scan
{
"type": "email",
"content": "suspicious@sketchy-domain.ru"
}Text scan
{
"type": "text",
"content": "URGENT: Your account is suspended. Send gift card..."
}Responses
Successful scans return HTTP 200 with a JSON body:
Response schema
| verdict | string | "safe" | "suspicious" | "likely_scam" |
| confidence | number | 0.0 – 1.0 detection confidence |
| risk_score | number | 0 – 100 overall risk |
| evidence | string[] | Up to 5 reasons for the verdict |
| next_steps | string[] | Recommended actions |
| scan_id | string | Unique ID for this scan |
| usage.calls_used | number | Calls used this month |
| usage.calls_limit | number | Your plan monthly limit |
| usage.resets_at | string | ISO 8601 reset timestamp |
likely_scam response
{
"verdict": "likely_scam",
"confidence": 0.94,
"risk_score": 92,
"evidence": [
"Detected as phishing website",
"Contains malware or malicious code",
"Flagged by threat intelligence"
],
"next_steps": [
"Do NOT visit this URL",
"Delete the message",
"Report to IT/authorities"
],
"scan_id": "v1_1711234567_ab3f9",
"usage": {
"calls_used": 142,
"calls_limit": 10000,
"resets_at": "2026-04-01T00:00:00.000Z"
}
}safe response
{
"verdict": "safe",
"confidence": 0.89,
"risk_score": 8,
"evidence": [
"No major threats detected",
"Risk score: 8/100 (low)",
"Domain age: 3847 days"
],
"next_steps": [
"URL appears safe",
"Still use caution with sensitive data"
],
"scan_id": "v1_1711234568_xy7k2",
"usage": {
"calls_used": 143,
"calls_limit": 10000,
"resets_at": "2026-04-01T00:00:00.000Z"
}
}safe
risk_score 0–49
No significant threat indicators. Low risk.
suspicious
risk_score 50–84
Some red flags present. Caution advised.
likely_scam
risk_score 85–100
High confidence threat. Do not engage.
Error codes
All errors return JSON with an error field describing the issue.
| Status | Meaning | Resolution |
|---|---|---|
| 401 | Unauthorized | Missing or invalid x-api-key header. Check your key. |
| 403 | Quota exceeded | Monthly call limit reached. Upgrade your plan or wait for the reset. |
| 422 | Invalid request | Missing or invalid type / content fields in request body. |
| 429 | Rate limited | Too many requests per second. Add exponential backoff and retry. |
| 503 | Service unavailable | Detection backend is temporarily unavailable. Retry after a few seconds. |
Rate limits
Every response includes rate limit headers so you can monitor usage programmatically.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Your plan's monthly call limit |
| X-RateLimit-Remaining | Calls remaining this month |
| X-RateLimit-Reset | ISO 8601 timestamp of next quota reset |
Monthly reset: All quotas reset on the 1st of each month at 00:00 UTC. Unused calls do not roll over.
Plans & pricing
Choose the plan that fits your volume. All API plans include the full endpoint and email support.
API Starter
$99/mo
10,000 calls/month
- ✓10K API calls/month
- ✓URL, email & text scanning
- ✓Full JSON responses
- ✓Rate limit headers
- ✓Email support
Best value
API Growth
$299/mo
50,000 calls/month
- ✓50K API calls/month
- ✓Everything in Starter
- ✓Priority support
- ✓Usage dashboard
- ✓SLA guarantee
API Enterprise
$499/mo
200,000 calls/month
- ✓200K API calls/month
- ✓Everything in Growth
- ✓Dedicated support
- ✓Custom integration help
- ✓Invoice billing
Need more volume?
Custom plans available for 500K+ calls/month. We can also offer white-label integration.