API Documentation

Integrate ScamSandbox into your application. Scan websites, retrieve results, and submit reports programmatically.

Getting Started

Base URL: https://scamsandbox.com/api/v1/

Format: All requests and responses use JSON.

Authentication: No API key required at this time. Rate limits apply.

Rate Limits: 60 requests per minute per IP address. Scan creation is limited to 10 per minute. If you exceed rate limits, you will receive a 429 Too Many Requests response.

POST /api/v1/scan/

Create a new scan for a URL, domain, or IP address. If a scan for the same target was created within the last 5 minutes, the existing scan is returned instead.

Request Body

{
  "target": "example.com",
  "target_type": "domain"  // "domain", "url", or "ip"
}

Response (201 Created)

{
  "scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "message": "Scan initiated successfully."
}

curl Example

# Create a new scan
curl -X POST https://scamsandbox.com/api/v1/scan/ \
  -H "Content-Type: application/json" \
  -d '{"target": "example.com", "target_type": "domain"}'
GET /api/v1/scan/{scan_id}/

Retrieve the full scan result including all source data, risk score, verdict, and timeline events.

Response (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "target": "example.com",
  "target_type": "domain",
  "risk_score": 23,
  "verdict": "safe",
  "is_complete": true,
  "sources_count": 18,
  "blacklist_count": 0,
  "source_results": { /* detailed per-source data */ },
  "created_at": "2026-03-15T10:30:00Z",
  "updated_at": "2026-03-15T10:30:45Z"
}

curl Example

curl https://scamsandbox.com/api/v1/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890/
GET /api/v1/scan/{scan_id}/status/

Lightweight endpoint to poll scan progress. Use this while a scan is running to check completion status without fetching full results.

Response (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "is_complete": false,
  "progress": 65,
  "sources_completed": 13,
  "sources_total": 20
}

curl Example

# Poll scan status
curl https://scamsandbox.com/api/v1/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status/
GET /api/v1/stats/

Get aggregate platform statistics including total scans, threats detected, and average risk score.

Response (200 OK)

{
  "total_scans": 15847,
  "threats_detected": 3291,
  "avg_risk_score": 34.2,
  "scans_today": 127
}

curl Example

curl https://scamsandbox.com/api/v1/stats/
GET /api/v1/history/

Get the most recent completed scans. Useful for showing a live feed of scan activity.

Query Parameters

limit (optional, default: 20, max: 100) — Number of results to return.

Response (200 OK)

[
  {
    "id": "...",
    "target": "example.com",
    "risk_score": 23,
    "verdict": "safe",
    "created_at": "2026-03-15T10:30:00Z"
  },
  // ... more results
]

curl Example

curl https://scamsandbox.com/api/v1/history/?limit=10
POST /api/v1/reports/

Submit a community report about a potentially dangerous website.

Request Body

{
  "domain": "suspicious-site.com",
  "reporter_name": "John Doe",
  "reporter_email": "john@example.com",
  "report_type": "phishing",  // "scam", "phishing", "malware", "fraud", "spam", "safe"
  "description": "This site impersonates a bank login page...",
  "money_lost": 0  // optional, in USD
}

Response (201 Created)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "message": "Report submitted successfully. Thank you for helping keep the internet safe."
}

curl Example

curl -X POST https://scamsandbox.com/api/v1/reports/ \
  -H "Content-Type: application/json" \
  -d '{"domain": "suspicious-site.com", "report_type": "phishing", "reporter_email": "you@example.com", "description": "Fake bank login page."}'
GET /api/v1/reports/list/?domain=

List community reports for a specific domain.

Query Parameters

domain (required) — The domain to get reports for.

Response (200 OK)

[
  {
    "id": "...",
    "domain": "suspicious-site.com",
    "report_type": "phishing",
    "description": "Fake bank login page...",
    "created_at": "2026-03-14T08:15:00Z"
  }
]

curl Example

curl https://scamsandbox.com/api/v1/reports/list/?domain=suspicious-site.com
POST /api/v1/removal-request/

Submit a request to remove or review a domain's scan results. Intended for site owners who believe their domain has been incorrectly flagged.

Request Body

{
  "domain": "my-legitimate-site.com",
  "requester_name": "Jane Smith",
  "requester_email": "jane@my-legitimate-site.com",
  "reason": "Our domain was flagged due to a temporary hosting issue that has been resolved..."
}

Response (201 Created)

{
  "message": "Your removal request has been submitted and will be reviewed within 48 hours."
}

curl Example

curl -X POST https://scamsandbox.com/api/v1/removal-request/ \
  -H "Content-Type: application/json" \
  -d '{"domain": "my-legitimate-site.com", "requester_name": "Jane Smith", "requester_email": "jane@my-legitimate-site.com", "reason": "Issue has been resolved."}'

Error Codes

Code Meaning
400 Bad Request — Missing or invalid parameters.
404 Not Found — The requested scan or resource does not exist.
429 Too Many Requests — Rate limit exceeded. Wait and retry.
500 Internal Server Error — Something went wrong on our end.

Questions about the API?

Contact Us